Documentation
For users to be able to implement a provider, they need sufficient information about how the service works. Thus, a provider:
- MUST describe the purpose of the API in a non-technical summary, a non-technical description (targeted at potential users, e.g. healthcare providers) and a technical description. These descriptions SHOULD describe possible uses or use cases for the API.
- SHOULD provide an image or logo pertaining to the API
- MUST describe the API with Swagger version 2.0 or OpenAPI version 3.0 (see https://swagger.io/specification)
- MUST document all API calls, parameters and possible responses
- SHOULD include descriptions and possible values
- SHOULD document the structure of the requests and responses
- MUST provide fully functional example requests or an example client on what to call the API
- SHOULD provide documents or URLs of publicly available documents describing the possible contents of a request and response, e.g. a reference to an ontology or thesaurus