"describedBy" link in API links section

[dret]

the current text provides an example for API-level information that is probably intended to link to API documentation, and uses the describedby link relation type. the idea to be able to link to API-level documentation is very useful, and it's good to have an example for it. However, describedby is probably not the appropriate choice here. typically, describedby is used to link to metadata describing the source resource, which in this case would be information such as the author of the home document, and maybe time stamps such as creation and last modification dates. https://tools.ietf.org/html/draft-wilde-service-link-rel provides link relations for the scenario used here: API level information. it defines service-doc, service-desc and status link relation types, which can be used to human-readable documentation (e.g., HTML), machine-readable description (e.g., OpenAPI), and a status resource. maybe these are a better fit for the home document scenario?

[dret]

i guess the point i was raising here is related to #191 (the question whether the service-* link relations might fit into JSON home).

[dret]

specifically, the example given currently looks like this:

    "api": {
      "title": "Example API",
      "links": {
        "author": "mailto:api-admin@example.com",
        "describedBy": "https://example.com/api-docs/"
      }

by using more specific link relations, the example could be changed to specifically link to human- and machine readable descriptions, for example one in PDF and the other one in OpenAPI.

    "api": {
      "title": "Example API",
      "links": {
        "author": "mailto:api-admin@example.com",
        "service-doc": "https://example.com/api-docs/api.pdf"
        "service-desc": "https://example.com/api-docs/api.oai"
      }

[dret]

would it help if i submit a PR replacing the more generic describedBy approach with the more specific service-* one?

[mnot]

Sure.