Add JSON hyperlinks for navigating API resources

[stain]

Following on from discussion in #153 I see there is a big challenge in that the TRS API do not follow the Hypermedia as the Engine of Application State principle - that is, the client is repeatedly forced to traverse JSON to pick up multiple key-values to then construct new URIs based on the Swagger templates.

It would be quite helpful, specially for new users of the API who may not know the TRS spec fully, to simply find links to the sub-resources along the line.

Say starting at a resource like https://workflowhub.eu/ga4gh/trs/v2/toolClasses - there are no links to search for /tools of the given type although that is presumably the main purpose of this listing.

I would suggest that all entries, specially in listings like /tools include hyperlinks so that the developer don't always have to hand-construct URIs like /tools/{id}/versions/{version_id} where they would otherwise have to make sure they don't mix up their id from their ids.

The JSON Hypertext Application Language (HAL) comes to mind, allowing you to add various short-cuts and save some unnecessary API calls by typing links with link relations

I am not suggesting we change it drastically to use their _embedded resources - although they are also interesting. Simply adding the informational _links blocks.

For instance - here showing our current non-TRS use of url could be combined with HAL _links sections for navigating the TRS API.

{
      "id":"2",
      "url":"https://workflowhub.eu/workflows/2",
      "_links": {
        "self": { "href": "/ga4gh/trs/v2/tools/2" },
        "version-history": { "href": "/ga4gh/trs/v2/tools/2/versions" },
        "latest-version": { "href": "/ga4gh/trs/v2/tools/2/versions/1" },
      },
      "name":"Genomics - Read pre-processing",
      "description":"Preprocessing of raw SARS-CoV-2 reads. More info can be found at https://covid19.galaxyproject.org/genomics/",
      "organization":"GalaxyProject SARS-CoV-2",
      "toolclass":{
         "id":"1",
         "name":"Workflow",
         "description":"A computational workflow",
         "_links": {
           "contents": "https://workflowhub.eu/ga4gh/trs/v2/tools?toolClass=Workflow"
         }
      },
      "versions":[
         {
            "id":"1",
            "url":"https://workflowhub.eu/workflows/2?version=1",
            "_links": {
              "self": { "href": "/ga4gh/trs/v2/tools/2/versions/1" },
              "version-history": { "href": "/ga4gh/trs/v2/tools/2/versions" },
              "predecessor-version": { "href": "/ga4gh/trs/v2/tools/2/versions/0" },
              "subsection": { "href": "/ga4gh/trs/v2/tools/2/versions/1/GALAXY/files" },
              "alternate": { "href": "https://workflowhub.eu/workflows/2?version=1", "type": "text/html"}
            },
            "name":"Genomics - Read pre-processing",
            "authors":[               
            ],
            "descriptor_type":[
               "GALAXY"
            ]
         }
      ]
   },

When there is no existing link relation appropriate one can use permalinks like https://w3id.org/ga4gh/trs/tests or just use _links: {self: {}} under its own JSON branch, as shown for versions above.

┆Issue is synchronized with this Jira Story
┆containerName: GA4GH tool-registry-service
┆Issue Number: TRS-46

[denis-yuen]

Found some reading here https://nordicapis.com/evolution-openapi-specification-openapi-mean-open-world/ which links to OAI/OpenAPI-Specification#577 which is still open.

Quickly browsing the discussion, it seems like there there isn't a pre-baked solution in the openapi tooling for this.
But informational _links blocks sound fine.

[uniqueg]

Real REST APIs? 😳 If done with care, I'm all for it! And the proposed _links sound useful and inoffensive to me as well. Interesting read @denis-yuen :)