4 Principles of REST API design

 

This chapter covers

  • The design principles of REST APIs
  • How the Richardson maturity model helps us understand the advantages of REST best design principles
  • The concept of resource and the design of endpoints for REST APIs
  • Using HTTP verbs and HTTP status codes to create highly expressive REST APIs
  • Designing high-quality payloads and URL query parameters for REST APIs

Representational state transfer (REST) describes an architectural style for applications that communicate over a network. Originally, the concept of REST included a list of constraints 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 learn to apply them by designing the orders API of the CoffeeMesh platform, the on-demand coffee delivery application we introduced in chapter 1.

We explain the concept of a 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 REST?

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

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