make HAPI more REST-ful using links to subsequent endpoints

[jvandegriff]

(Jon V): I'm unceremoniously putting Bobby's email in here:

An addition to the HAPI spec could meet Aaron's request that HAPI links be usable by users directly. As Bernie pointed out, his HAPI implementation presents a different more client friendly interface when called with accept header of HTML. The REST concept HATEOS https://en.wikipedia.org/wiki/HATEOAS calls for returning links for dynamically discovering the actions and resources possible (affordances) from there, without manual intervention. This could be in a more readable form when called with accept of HTML as Bernie did.

HATEOAS REST Services With Spring https://dzone.com/articles/hypermedia-driven-rest-services-with-spring-hateoa Design principles of the REST-ful JSON API (HATEOAS) http://perpetuum-mobile.net/tech/design-principles-of-the-rest-ful-json-api-hateoas/

The top level call /hapi/ (not /hapi) would return

  "HAPI": "2.1",
  "status": { "code": 1200, "message": "OK" },
  "link": { rel="capabilities", href="/hapi/capabilities" },   # could wrap these two links in a "links": {} section
  "link": { rel="catalog", href="/hapi/catalog" }
}```

A call to /hapi/catalog would return
```{
   "HAPI" : "2.1",
   "status": { "code": 1200, "message": "OK"},
   "catalog" :
   [
      {"id": "ACE_MAG", title:"ACE Magnetometer data", "link": { rel="info", href="/hapi/info?id=ACE_MAG" } },
...
   ]

A call to /hapi/info?id=ACE_MAG would return

   "status": { "code": 1200, "message": "OK"},
   "startDate": "1998-001Z",
   "stopDate" : "2017-100Z",
   "parameters": [
       { "name": "Time",
         "type": "isotime",
         "units": "UTC",
         "fill": null,
         "length": 24,
         "link": { rel="data", href="/hapi/data?id=ACE_MAG&parameters=Time&time.min=1998-001Z&time.max=2017-100Z" } },
... <last variable>
   ],
    "link": {rel="all_variables", href="/data?id=<ProductID>&time.min=1999Z&time.max=2000Z" }

or perhaps more useful: "link": {rel="all_variables", href="/data?id=<ProductID>&parameters=Time,mag_GSE,quality_flag,,...&time.min=1998-001Z&time.max=2017-100Z" }

and for the complaint of not storing the calling sequence:

"link": {rel="self", href="/hapi/info?id=ACE_MAG" }

From REST API — What Is HATEOAS? https://dzone.com/articles/rest-api-what-is-hateoas and Creating a hypermedia-driven RESTful web service https://openliberty.io/guides/rest-hateoas.html, we could perhaps use the name "_links" instead of "link" or maybe its own _links section, with multiple link sections (the rel= is standard HTML but maybe not necessary):

  "_links": { "capabilities": { href="/hapi/capabilities" },  
                    "catalog": { href="/hapi/catalog" } }

  "_link": { "data": { href="/hapi/data?id=ACE_MAG&parameters=Time&time.min=1998-001Z&time.max=2017-100Z" } }

[jvandegriff]

related to issue #101

[jvandegriff]

would require major overhaul, so not likely at this point; would need a champion to proceed

[jvandegriff]

telecon on 2021-05-24

Could be done as an optional mechanism: add trailing slash to URL to get extra links to the next level links

Idea is to make it self-documenting for someone typing link to a browser so they could teach themselves how to use it by just typing the top link, and then following subsequent links.

could expose this as an option in the capabilities endpoint.

Output would need to be HTML for browsers.

Jeremy: could do this by requiring the top-level hapi endpoint to be an official / standardized explanation.

Lower priority for now.

[jvandegriff]

This is tied to our re-look at the whole API, especially in terms of the OpenAPI community.

Until then, we should not make these kinds of big changes.