3 Observing operations from the REST angle

This chapter covers

The basics of HTTP and REST APIs
Identifying resources and their relations
Identifying resources' actions and their inputs and outputs

Now that we have analyzed users’ needs and identified the API capabilities required to fulfill them, especially the operations, we can start turning their plain English (or any other language) descriptions into the programming interface. In the context of this book, this means designing a REST web API. It requires knowing the basics of HTTP and REST APIs, which the sample without explanation in section 1.1.2 didn’t teach us. We still have no clue how an operation like “Send a message” can be turned into a POST /status, POST /message, or POST /messages HTTP request. Additionally, designing such a programming interface covers different aspects we must know and separate to simplify our learning and work while ensuring that our API design is accurate and versatile.

This chapter examines the “Design the programming interface” step of the API design process by explaining the basics of HTTP and REST APIs and how to design a REST API. Then we focus on our first task within this step: observing the operations we identified from the REST perspective. This consists of identifying the business concepts with which the API deals, called resources in REST APIs, how they relate, the actions that apply to them, and their inputs and outputs.

3.1 An overview of programming interface design

3.1.1 Introducing the basics of the HTTP protocol

3.1.2 Introducing the basics of REST APIs

3.1.3 Contrasting REST with non-HTTP-compliant web APIs

3.1.4 How do we design a REST programming interface?

3.1.5 Why not discuss HTTP and REST when identifying capabilities?

3.2 Observing the API Capabilities Canvas from the REST angle

3.2.1 Reorganizing and expanding the API capabilities canvas

3.2.2 How to observe operations from the REST angle

3.3 Identifying resources and their relations

3.3.1 What is a resource?

3.3.2 Identifying an operation’s resource

3.3.3 Tweaking an operation’s description to identify resource

3.3.4 Identifying resource relations

3.3.5 Using patterns and recipes to identify resources and relations

3.4 Identifying resource actions

3.4.1 What is an action, and how can it be identified?

3.4.2 Listing an action’s inputs

3.4.3 Dealing with the operation’s resource when listing an action’s inputs

Summary