Here are some recommendations for your implementation

Handling requests

Our recommendation is to support the following apicalypse delivery methods and return the same response for each:

  • Apicalypse can be urlencoded and attached to a URL parameter in a GET request.
  • Apicalypse supplied in the body of a GET request and at least one alternative method (see below for recommendations).

The limitations of the URL parameter are that a large query may exceed the URL size limit.

When using a GET request body, some considerations need to be made.

  • Some ISP, Proxy, VPN, code libraries and frameworks simply do not support a GET body. For example, browser-based Javascript cannot supply a body in a GET request.
  • If the client is coming from a guaranteed environment (such as a hosted server) who’s network and code do support a GET body, then it is ok to omit other methods.
  • If the client has varying devices, networks or other unknowns, an alternative method should be used in addition.
    • Alternative recommended methods are POST or PUT.
    • Alternative recommended methods with limitted client support are SEARCH and VIEW.

The server can use Content-Type: application/apicalypse to differentiate request types if needed.