Chapter 2: Understanding HTTP, REST and APIs

Design and Build Great Web APIs — by Mike Amundsen

HTTP, short for hypertext transfer protocol, is an open standard to make sure machines talk to each other over the Internet. Most APIs on the web rely on this protocol. HTTP standard is currently managed by Internet Engineering Task Force (IETF).

Basics of HTTP —

a) The HTTP message: HTTP defined a single text-message format for all requests and responses.

b) HTTP methods: To ensure both the sender and receiver understand each other, HTTP defines a set of method names that we need to deal with when implementing APIs.

When creating web APIs, its important to remember that we are building on top of the existing web. It is not a standard protocol like HTTP, but just a set of practices that use clear agreed-upon standards. It relies on hypermedia to create a linked information system and is build in a way that makes it easy to get started and supports small changes over time.

The Style of REST

REST or Representational State Transfer is software architecture that runs on networks like Internet. It was described in a chapter of a PhD dissertation published by Roy Fielding.

Fielding basically described REST style as a set of constraints that are selected based on the set of architectural properties of key interest. Below are defined the list of valuable properties of the web as defined by Fielding and a set of rules that software developers would need to follow in order to realize the best aspects of web.

Properties that every web-based system should do:

• Performance: Offer high performance through design.
• Scalability: Support large numbers of machines that are easily configured and deployed.
• Simplicity: Rely on the principle of the separation of concerns and the generality of interfaces.
• Modifiability: Make it easy to modify a running system to support changes overtime.
• Visibility: Make it easy to monitor and manage running components
• Portability: Make it easy to provide the same functionality in different environments, operating systems and so on.
• Reliability: Make it unlikely for the failure of a single component to impact the entire system.

REST Constraints

• Client-server: Implement a clear separation between the server and the client app with the request/response interactions.
• Stateless systems: Make sure each request from the client contains all thats needed to complete that request. Don’t rely on any request context information stored on the server.
• Cache: Make it possible for clients to know whether the server response can be cached locally and replayed in the future.
• Uniform Interface: Apply the generality of interface patterns between all components.
• Layered System: Each component should only be aware of the next component in the chain and not know about other layers of components in the system.
• Code of demand: Client applications should be extensible through the use of downloadable code-on-demand instead of having to build new client applications for each new feature.

Thus, we can improve the quality of our APIs by using the HTTP’s message-based approach, adopting web’s use of small set of standards and applying the REST style of constraints to build more consistent solutions.