Including code descriptions in responses

[pvdbosch]

Formulate guidelines:

• when to include descriptions of codes: in each message, or only in refData resources.
• when to include href links to code descriptions: only when target in in same API?

Related:

• link to code description via mapping to a URI via JSON-LD (but this would be the semantic web URI rather than an API's refData)
• OpenAPI 3 supports to specify (links to document how to create URL of a referenced resource based on a response value

This discussion could be extended to other metadata for codes (e.g. validity period)

Guidelines could allow some options depending on clients that an API is targeting, e.g. backend-only (business data), or for a user interface (Backend For Frontend API).

[pvdbosch]

some notes from WG 2022-12:

• defining URIs (~ semantic web) stimulate harmonization of codes
• clients often do only calls within single API or domain to retrieve code descriptions (URIs can be hosted by lots of different organizations and domain names). A BFF API often re-published these codes and caches their values. ** but authentic source of code lists does not always expose an API with the code description, and only provide inline descriptions in messages
• complexity when referring to a concept using both code and URI when there are modifications: e.g. to handle inconsistencies

[pvdbosch]

eHealth: no hrefs currently Smals: inconsistent between APIs, only hrefs within single API

[JDMKSZ]

It seems to me that adding hrefs only it the most RESTful? See this SO post + the link to the Fielding article

[pvdbosch]

Using only hyperlinks to look up and navigate between resources (HATEOS) is indeed part of the original REST principles of Roy Fielding, but in practice doesn't seems feasible with current technological state of REST APIs. Some more background on this can be found here in the zalando rest guide. REST clients tend to use URI templates or be hardcoded in another way to the API's URI space (i.e. with code generation from OpenAPI).

Using the href links from responses might be more common for JavaScript clients, but I think it's overall less used then constructing the URI from a URI template (which may be generated from OpenAPI).

I'd propose to amend to guide to limit the use of "href" linking (in combanation with the resource identifier) only for resources within the same API to ensure low coupling between different APIs (e.g. no impact when there's new major version of an API).

[pvdbosch]

agreed in WG to specify that "href" should only be used to refer within the same API. Further rules are difficult to generalize for every use case.