allow servers to give info response as human readable HTML instead of JSON

[jvandegriff]

This came up when talking about how to represent HAPI access in a SPASE element.

Bernie suggested that if a HAPI server gets a request with an Accept header indicating HTML preference, this means it's a browser, so a human readable HTML response is appropriate.

This issue proposes that the spec be changed to allo HAPI servers to do this. The HTML that they return would be server specific, and could include instructions to humans with code snippets about how to access the data via Python, IDL, Matlab, etc.

The default (given no Accept header) would be JSON, and servers would not need to pay attention to the HTML request.

Here is Bernie's description of what he did in his original CDAWeb HAPI server:

here's an example of my info response that requires no change to HDP (the reason I did it) if it were used in a spase NumericalData/AccessInformation/AccessURL/URL element:

https://cdaweb.gsfc.nasa.gov/registry/hdp/hapi/info?id=spase://NASA/NumericalData/ACE/MAG/L2/PT16S

When viewed with a browser, you'll see html because browsers sends an Accept header with a value something like " text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,/;q=0.8". But if you do

$ curl -s "https://cdaweb.gsfc.nasa.gov/registry/hdp/hapi/info?id=spase://NASA/NumericalData/ACE/MAG/L2/PT16S" | jq
or
$ curl -s -H "Accept: application/json" "https://cdaweb.gsfc.nasa.gov/registry/hdp/hapi/info?id=spase://NASA/NumericalData/ACE/MAG/L2/PT16S" | jq

you'll get JSON (or XML if you specify "application/xml").

Note that this could potentially also apply to other endpoints.

[berniegsfc]

The reason I did this was to allow an info url to be used for a SPASE AccessURL when I was told that the AccessURL had to return HTML. So this issue should be considered with issue #56. The resolution of issue #56 may eliminate the need for this.

[jvandegriff]

There are likely going to be other servies that get described in the <AccessURL> element in SPASE. I think it is unlikely that the SPASE group will propose that all service descriptions within the <AccessURL> provide a URL that returns human readable ASCII. So services like the Heliophysics Data portal that want to show human friendly renderings of the access URL will need some code to be able to render the URL into whatever context they think is appropriate for their users.

Perhaps the <AccessURL> element needs an 'element (or maybe`) that informs users about how to use a service. People know about HTTP, and FTP, or SFTP, since they are well-known standards, but HAPI and other services will need some explanation.

[jvandegriff]

We explored wether we could close this, but there is still enough interest that it needs discussion. It's lower priority than other issues, so we are holding off further discussion and decisions for now.

Everyone thinks that it would be good to have a convenient way for users to learn how to use a server - that showing humans (i.e. browsers) more than just raw JSON would be useful for an info response. The debate is about where to add that functionality. Maybe a separate service provides this for all HAPI servers. Or maybe the standard server implementation provides this capability, so most servers get it for free. It's optional anyway.

Or perhaps, a server should advertise wether it can do this - via the existing capabilities end point.

[jvandegriff]

For people that want to do this, the spec should give an indication of how, so that we don't end up with many ways of doing it.

[jvandegriff]

no one is pushing this now - need to find a champion or we should close it

[jvandegriff]

The best way to handle this is to have the web server (that is presenting the HAPI info) do the rendering of the HAPI JSON metadata. This means HAPI servers focus only on the JSON, which is machine readable, and the HAPI spec does not need to get into the details of HTML rendering. Also, the web portal showing the HTML can use HTML that is consistent in look and feel to the rest of the web site.

Closing since no changes to the spec are going to be done for this.