3.3. REST: Practical Fundamentals¶

3.3.2.1. Identifying the Resource¶

Paths are used to identify the resource. Recall the hierarchal nature of resources where an entity only exists within a collection.

RESTful APIs separate the resources they expose into one or more resource entry-points. As the name implies, these entry-points are the start of the hierarchy, and they identify each top-level resource collection.

Let’s consider two resources exposed by a RESTful API:

Notice that the entry-points are pluralized. The pluralized path indicates that the state of the resource collection is the subject of the interaction.

Consider a request to the following endpoint (path and method):

Let’s see this in action with our example API. Using what we have learned so far, we can expect the state of the resource collection to be represented in a JSON array, []:

[
   CodingEvent { ... },
   ...
]

[
   Tag { ... },
   ...
]

Suppose we wanted to interact with an individual resource entity. We would need to identify it within its collection.

The path to identify a resource entity would need to include:

• The collection identifier, or resource entry-point (/collection).
• The unique resource entity identifier (/{entityId}) within the collection.

Because the unique identifier of the entity is variable we use a path variable ({entityId}) to describe it in a generic way.

Consider a request to the following endpoint for viewing a single resource entity:

Let’s take another look at our example API:

{
   "Id": 12,
   "Title": "Halloween Hackathon!",
   "Description": "A gathering of nerdy ghouls...",
   "Date": "2020-10-31"
}

3.3.2.2. CRUD Operations & HTTP Methods¶

In a RESTful API the interactions a client takes on a resource are described using HTTP methods.

If the resource path describes the noun (subject) the HTTP method describes the verb (action) that is taken on that subject’s state.

As we saw in the previous article, state is something that can be interacted using CRUD operations. By convention, each of these operations corresponds to an HTTP method:

The use case of an API dictates the design of its contract. This includes which actions the client can take on each resource. In other words, not every action must be exposed for each resource the API manages.

3.3.3.1. Operating on Collections¶

Let’s consider a request for creating a resource entity. Recall that this operation acts on the state of the collection by adding a new entity to it.

The POST endpoint of the collection, that the entity belongs to, can be used with a request body. This request body is a representation of the initial state the client must provide as an input to the API.

Let’s take a look at a request in the context of our example API:

NewCodingEvent {
   Title: string
   Description: string
   Date: string (ISO 8601 date format)
}

3.3.3.2. Operating on Entities¶

When removing a resource the client is requesting a transition to an empty state. This means that both the request and response body that are transferred—the representations of state—are empty.

We can see this behavior in action with a request to the DELETE endpoint for a single resource entity in our example API:

3.3.4.1. Status Codes¶

Every RESTful API response includes a status code that indicates whether the client’s request succeeded or failed.

{
   "Title": "short"
}

{
   "error": "invalid fields",
   "fields": [
      {
         "Title": "must be between 10 and 100 characters in length"
      }
   ]
}

3.3.4.2. Headers¶

In RESTful design headers are used to communicate metadata about each interaction with a resource.

3.3.5.1. Practical Understanding¶

• Craig Dennis: APIs for beginners (YouTube)
• REST sub-collections, relationships and links
• OpenAPI specification & Swagger REST tools
• The GitHub API and Stripe (payment processing) API are excellent examples of RESTful design (and fantastic documentation)

3.3.5.2. Deep Understanding¶

• The REST constraints
• The The Richardson REST maturity model
• The original REST doctoral thesis by Roy Fielding