Saturday, April 30, 2016

HTTP/REST API Specifications

Now that I have the pleasure of designing new APIs to support both B2C and B2B use cases, my first thought is to standardize. In the case of APIs, I believe standards reduce the burden of maintenance and improve the ease of integration.

To that end, I sought to define guidelines for all operations. These are not new or novel, but I need these to set shared expectations with my team. And we start with a few core principles:

  1. Follow REST conventions for CRUD operations
  2. Use JSON in all request and response bodies (Content-Type: application/json)...
  3. Except where binary content is involved (Content-Type: multipart/form-data)

REST conventions


Striving to KISS:

Error response body


Success responses will contain appropriate data for the request, but all error response bodies look alike. At least structurally, having only one field.

  • Array<Error> errors - An array of any errors encountered while executing the operation. This field is always present for an error state (any non-200 HTTP status).


Each errors element has the following fields:

  • int code - "for programmatic consumption" (ref Braintree)
  • String message - "for human consumption" (ref Braintree)
  • String component - Whatever we're blaming for the error