API semantics #44
Description
Instead of building on a linked data platform, we have chosen to implement an API. As it is a versioned datastore that exposes predictable links to its endpoints at its root, one could argue we are talking about a hypermedia API. Why then would we want to tap around in the dark, instead of choosing design guidelines for our work?
There are multiple standards known, and utilised to varying degrees. https://en.wikipedia.org/wiki/Overview_of_RESTful_API_Description_Languages
Most recommended is Swagger (now OpenAPI) for its integration with Swagger-UI.