3 Designing a programming interface

In the previous chapter, you learned how to identify an API’s goals—what users can achieve using it. For a Shopping API, some of these goals could be search for products, get product, add product to cart, check out cart, or list orders. These goals form the API’s functional blueprint that we will use to design the actual programming interface that is consumed by its users (developers) and their software. To design this programming interface, we will transpose these goals and their inputs and outputs according to an API style, as shown in figure 3.1.

REST stands for Representational State Transfer. Here, the REST API style transposes the get product goal into a programming interface. It is represented by a GET /products/{productId} request, where productId is an input parameter (here its value is P123), and a 200 OK is a response with some output data consisting of the reference, name, and price properties. How do we design such a programming interface?

3.1 Introducing REST APIs

3.1.1 Analyzing a REST API call

3.1.2 Basic principles of HTTP

3.1.3 Basic principles of REST APIs

3.2 Transposing API goals into a REST API

3.2.1 Identifying resources and their relationships with the API goals canvas

3.2.2 Identifying actions and their parameters and returns with the API goals canvas

3.2.3 Representing resources with paths

3.2.4 Representing actions with HTTP

3.2.5 REST API and HTTP cheat sheet

3.3 Designing the API’s data

3.3.1 Designing concepts

3.3.2 Designing responses from concepts

3.3.3 Designing parameters from concepts or responses

3.3.4 Checking parameter data sources

3.3.5 Designing other parameters

3.4 Striking a balance when facing design challenges

3.4.1 REST trade-off examples

3.4.2 Balancing user-friendliness and compliance

3.5 Understanding why REST matters for the design of any API

3.5.1 Introducing the REST architectural style

3.5.2 The impact of REST constraints on API design

Summary