Understanding JSON Patch

The typical update cycle for an API resource is to (1) GET the representation, (2) modify it and (3) PUT back the entire representation. This can waste bandwidth and processing time for large resources. An alternative is to use the HTTP PATCH extension method to only send the differences between two resources. HTTP PATCH applies a set of changes to the document referenced by the HTTP request.

[Read More]
json  patch  api  rest 

How to Version a REST API

API versioning is a fact of life. Even the most well designed API changes as new features and relationships are uncovered. Unfortunately, updating an API is seldom as simple as changing the behaviour of our existing URL endpoints on her he server. If we have existing clients we need to explicitly advertise breaking changes in a seamless way. This article explains a few methods of specifying breaking changes that offer a clear upgrade path for existing API clients.

[Read More]

When to Use HTTP PUT and HTTP POST

The HTTP protocol defines two methods for updating a resource – PUT and POST. Both PUT and POST are used to modify a resource and this semantic similarity can confuse API developers. This confusion has led most developers to use POST for any action which may modify the state of a resource, ignoring PUT entirely.

This article attempts to explain the semantics behind the PUT and POST methods and offers clear suggestions on when to use each method.

[Read More]
hypermedia  rest  api  post  put 

How REST Constraints Affect API Design

REST was developed and formalized by analyzing the existing Web and extracting the principles that made it work. This set of principles was written down in the Fielding dissertation which lays out the set of constraints that, when enforced, will make a generic network system into a resilient network like the Web. In Chapter 5 of the dissertation Fielding outlines REST’s interface constraints.

REST is defined by four interface constraints: identification of resources; manipulation of resources using representations; self-descriptive messages; and, hypermedia as the engine of application state.

[Read More]