4 Representing operations with HTTP

After reviewing the API Capabilities Canvas from a REST perspective and identifying resources, actions, inputs, and outputs, we can translate “Send a message” into a POST /messages or POST /message request. However, challenges can arise in representing the resource (“message”) with a path (/messages or /message) and mapping the freely defined action “Send” to standard HTTP methods like POST. These examples reveal only a few aspects of a request; more considerations are needed for accurately mapping all the identified elements to HTTP requests and responses. Additionally, not all operations fit neatly in typical create, search, read, update, and delete categories; some are simply verbs, such as “like.” These verb-based “do” operations can complicate HTTP representation.

4.1 Representing operations with HTTP

4.1.1 What an operation looks like with HTTP

4.1.2 How to represent operations with HTTP

4.2 Representing resources with paths

4.2.1 What is a resource path?

4.2.2 Designing meaningful resource paths

4.2.3 Targeting specific elements with path parameters

4.2.4 Showing resource relationships with a hierarchy

4.2.5 Representing lists and their elements

4.3 Representing actions with HTTP methods

4.3.1 Determining which HTTP methods to use

4.3.2 Choosing HTTP methods to represent actions

4.3.3 Representing search, read, and delete actions

4.3.4 Representing update actions

4.3.5 Representing create actions

4.3.6 Mapping typical operations to HTTP

4.4 Choosing input data locations in HTTP requests

4.4.1 Where to put input data in an HTTP request

4.4.2 An overview of input data natures

4.4.3 Choosing a location for resource identifiers

Summary