Since these guidelines were originally formulated, technologies used for the type of APIs relevant to Quisper® have been updated. The HAL/JSON format has not seen widespread uptake and, in some cases, was verbose to implement. On the other hand, Swagger and OpenAPI specifications have become more important. They allow a provider to describe accurately the types of data an API will accept and return. In addition, users can be generated automatically from a Swagger or OpenAPI definition. Thus, the guidelines for linking to Quisper are:

1. Use a RESTful API (e.g.

  • Distinguish between HTTP methods (GET, POST, PUT, DELETE)
  • Use HTTP status codes for meaningful feedback

2. Uniform REST URL naming (e.g.

  • Use URLs representing the webservices content rather than provider name(s), as these will be more useful
  • Make use of a hierarchical URLs, as clarifies the intention of a URL and simplifies the API documentation process
  • Only use lowercase letters, numbers and, if needed, hyphens
  • Use nouns
  • Use plurals for collections
  • Avoid acronyms

3. Use JSON in requests and responses where possible and use content negotiation headers for other data formats

4. Request and response body sizes may not exceed 10 MB (10485760 bytes).