Designing a Swagger API
Creating RESTful APIs with App Engine Cloud Endpoints
App Engine Cloud
Endpoints is a
great way to quickly and easily create JSON API endpoints. What’s not clear is
how to structure your
Message code to support a RESTful
create-read-update-delete (CRUD) API. This article will show the basic CRUD
operations for one Resource. The results can easily be adapted to support a full
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]
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 –
POST are used to modify a resource and this semantic
similarity can confuse API developers. This confusion has led most developers to
POST for any action which may modify the state of a resource, ignoring
This article attempts to explain the semantics behind the
methods and offers clear suggestions on when to use each method.
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.
On choosing a hypermedia type for your API - HAL, JSON-LD, Collection+JSON, SIREN, Oh My!
In recent years REST has been at the forefront of modern API design. This has led to APIs with manageable URLs that respect the HTTP verbs (GET, POST, PUT and the rest), producing an intuitive model for client developers. Unfortunately, there are two problems that REST doesn’t solve alone.[Read More]