1. August 2016

2. Fundamental essentials for (RESTful) API design and configurations

Many of the API design opinions found on the web are academic discussions revolving around interpretations of uncertain standards as opposed to what makes sense in the real world. The aim of this presentation is to describe the best common practices in the IT industry for practical API design for all web applications.

Requirements that make RESTful APIs appealing

According to Dr Roy Fielding, these are:

  • Scalability – not necessarily its performance, yet rather how easy it is for RESTful APIs to adapt and grow and be plugged into other systems.
  • Use of HTTP protocols – using HTTP methods to manage resources makes RESTful APIs easy to plug into other applications.
  • Independency – with a RESTful API you can deploy or scale down specific parts of the application without having to shut down the entire application.
  • Reduced latency due to caching – REST APIs prioritize caching, which helps improve latency. Keep caching top of mind while developing your REST API.
  • Security – HTTP specification allows you to leverage certain HTTP headers for enhanced security.
  • Encapsulation – REST allows you to encapsulate parts of the application that don’t need to be exposed, only showing what's necessary.

Why JSON?

  • Ubiquity – over 57% of all web-based applications using JSON are built on JavaScript or have JavaScript components.
  • Human-readable – it uses simple grammar, making it easy to read, especially for new developers.
  • Fields – it’s easy to change or add new fields.

RESTful design difficulties

RESTful APIs are complex to design because REST is an architectural style, not a specification. There are varied interpretations of how HTTP protocol works, leading to diverse design approaches.

Use RESTful URLs and actions

Key principles of REST involve separating your API into logical resources manipulated using HTTP requests (GET, POST, PUT, DELETE).

HTTP methods clarified

The common HTTP methods used by most RESTful web APIs are:

  • GET - to retrieve a copy of the resource at the specified URI.
  • POST - to create a new resource at the specified URI.
  • PUT - to replace or update the resource at the specified URI.
  • DELETE - to remove the resource at the specified URI.

Singular or plural endpoints

Use a plural format for URLs consistently to avoid odd pluralization that complicates API consumption.

How to deal with relations

If a relation only exists within another resource, follow RESTful principles. For example, a coupon consisting of several messages might have endpoints like:

  • GET /coupons/12/messages - Retrieves list of messages for coupon #12.
  • GET /coupons/12/messages/5 - Retrieves message #5 for coupon #12.
  • POST /coupons/12/messages - Creates a new message in coupon #12.
  • PUT /coupons/12/messages/5 - Updates message #5 for coupon #12.
  • DELETE /coupons/12/messages/5 - Deletes message #5 for coupon #12.

Actions that do not fit into CRUD operations

When actions can’t be structured as CRUD, consider:

  • Restructuring the action as a resource field.
  • Treating it as a sub-resource.
  • Using a suitable endpoint that doesn’t correspond to a specific resource if necessary.

SSL at all times

Always use SSL to ensure secure communication. Avoid redirecting non-SSL requests; respond with a hard error instead.

Documentation is the way forward

Documentation should be easily accessible and demonstrate examples of request/response cycles. Effective documentation promotes easy integration.

Versioning is always best

Versioning helps maintain and evolve the API without disrupting existing integrations.

Result filtering, sorting & searching

Keep base resource URLs lean; utilize query parameters for:

Filtering

Use unique query parameters for filtering, e.g., GET /coupons?state=open.

Sorting

A sort parameter can guide sorting, e.g., GET /coupons?sort=-priority.

Searching

For full-text search, use query parameters, e.g., GET /coupons?q=return.

Caching

Implement ETag and Last-Modified headers for efficient response caching, improving performance.

Errors

Provide informative error messages in JSON format with unique error codes and descriptions:

{
  "code": 400,
  "message": "Something bad happened :(",
  "description": "More details will follow soon"
}

HTTP status codes

Use meaningful HTTP status codes to help API consumers understand responses. Commonly used ones include:

  • 200 OK – Successful response.
  • 201 Created – Resource created.
  • 400 Bad Request – Malformed request.
  • 401 Unauthorized – Authentication needed.
  • 429 Too Many Requests – Rate limiting triggered.

Last thoughts

An API is a UI for developers; ensure it's functional and user-friendly.