api

The goal of Swagger is to define a standard interface for describing REST APIs. In an ideal world, a Swagger definition for your API will allow both humans and computers to discover and understand your API. At it’s core, Swagger is a formal specification of an API. Surrounding this specification are a wide swath of tools to support creating documentation, providing client libraries, and managing API deployments. One of Swagger’s original goal was to provide a way to document an API in both a human and machine readable way. [Read More]

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 REST API.

[Read More]

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]

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]

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]

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]

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]