Add signpost in HTTP header #1

As far as I understand the metadata of the API should be kept in a repository according to the paper. I have a suggestion: I think that in the API response, the Link HTTP header would be a good place for a URL pointing to the smartAPI description. Herbert van de Sompel suggested this method in his Memento [1] and Signposting [2] initiatives, and I think the idea could be reused here as well. Signposting already suggested to use the "describedby" relation to bind object and metadata description. Van de Sompel gives the following usage example (in the context of an institutional repository):

curl -I "https://doi.org/10.1007/s10958-016-2844-8"

Link: https://doi.org/10.1007/s10958-016-2844-8
; rel="describedby"
; type="application/vnd.citationstyles.csl+json"

In a smartAPI it would be something like that

curl -I "https://example.com/smartAPI?...."

Link: http://smart-api.info/api/metadata/...
; rel="describedby"
; type="application/json; charset=UTF-8"

This kind of link would help the discoverability of the API metadata, and thus the life of the developers of API clients, who might be not aware of the existence of smartAPI documentation, but check the HTTP headers routinely.

[1] the most recent paper I read: Sande - Verborgh - Hochstenbach - Sompel, Toward sustainable publishing and querying of distributed Linked Data archives (Journal of Documentation, 2018) http://linkeddatafragments.org/publications/jod2017.pdf, and Miel van der Sande's doctoral thesis at https://biblio.ugent.be/publication/8551528

[2] http://signposting.org/

Best,

Péter

Péter Király
GWDG - Gesellschaft für wissenschaftliche
Datenverarbeitung mbH Göttingen
Am Faßberg 11, 37077 Göttingen
www.gwdg.de