4 Principles of REST API design

Representational State Transfer (REST) describes an architectural style for applications that communicate over a network. Originally, the concept of REST included a list of constrains for the design of distributed and scalable web applications. Over time, detailed protocols and specifications have emerged that give us well-defined guidelines for designing REST APIs. Today, REST is by far the most popular choice for building web APIs^[1]. In this chapter, we study the design principles of REST, and we learn to apply them by designing the orders API of the CoffeeMesh platform, the on-demand coffee-delivery application we introduced in section 1.5.

We explain the concept of resource, and what it means for the design of REST APIs. You’ll also learn to leverage features of the HTTP protocol, such as HTTP verbs and status codes, to create highly expressive APIs. The final part of this chapter covers best practices for designing API payloads and URL query parameters.

4.1 What is Representational State Transfer?

4.2 Architectural constraints of REST applications

4.2.1 Separation of concerns: the client-server architecture principle

4.2.2 Make it scalable: the statelessness principle

4.2.3 Optimize for performance: the cacheability principle

4.2.4 Make it simple for the client: the layered system principle

4.2.5 Extendable interfaces: the code on demand principle

4.2.6 Keep it consistent: the uniform interface principle

4.3 Hypermedia as the Engine of Application State (HATEOAS)

4.4 Analyzing the maturity of an API with the Richardson Maturity Model

4.4.1 Level 0: web APIs à la RPC

4.4.2 Level 1: introducing the concept of resource

4.4.3 Level 2: using HTTP methods and status codes

4.4.4 Level 3: API discoverability

4.5 Structured resource URLs with HTTP methods

4.6 Using HTTP Status Codes to create expressive HTTP responses

4.6.1 What are HTTP status codes?

4.6.2 Using HTTP status codes to report client errors in the request