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
  • 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