4 Designing a RESTful API

This chapter covers

The constraints that underpin the design principles of REST APIs
How the Richardson Maturity Model can help us understand the advantages of REST best design principles
The concept of resource in REST APIs
Designing API endpoints by combining CRUD with the concept of resource
Using HTTP verbs and HTTP status codes to design meaningful requests and responses for REST APIs
Using URL query parameters and request payloads in designing our API endpoints

The concept of Representational State Transfer (REST) was developed by Roy Fielding to describe an architectural style for applications that communicate over a network. Originally, the idea of REST defined a number of constrains that applications need to meet in order to be considered RESTful. Over time, with the increasing popularity of REST, more detailed protocols and specifications have been developed that give us well-defined guidelines about how to design our APIs. Today, REST is by far the most popular choice for the implementation of web APIs. In this chapter, we study the protocols and specifications defined in REST, and we see how we can use them to design the specification for the API of the orders microservice of the CoffeeMesh application.

4.1 Design principles of REST APIs

4.1.1 What is Representational State Transfer?

4.1.2 Constraints of a RESTful application

4.1.3 Hypermedia as the Engine of Application State (HATEOAS)

4.1.4 The Richardson Maturity Model

4.2 Applying CRUD to the design of REST APIs

4.3 REST over HTTP: leveraging HTTP for meaningful API communication

4.3.1 Using HTTP verbs to create meaningful HTTP endpoints

4.3.2 Using HTTP Status Codes to create meaningful HTTP responses

4.3.3 Returning meaningful responses to the API clients

4.4 Request payloads and URL query parameters

4.4.1 Using payloads to send data to the server

4.4.2 Using URL query parameters to filter resources

4.5 Summary