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:

• Prefix all operations with a major version number, starting with "/v1" (ref PayPal, Salesforce)
• Stick with lowercase (ref Heroku)
• Map HTTP methods to CRUD operations (ref REST API Tutorial)
• Use route parameters for CRUD operations (ref Express)
• Use query strings only in GET requests

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