REST: Practical Fundamentals

Here’s a takeaway of the abstract ideas we covered on the last page:

• State: data that can change (transition) through interactions between an API and its client

• Representation: the convertible format that enables state to be transferred and used by the client and API

• Resource: the representation of a type of state (as an entity or collection) that the API exposes to its client for interaction

Now that you have an understanding of these concepts, let’s turn our attention to the practical details of working with REST APIs. The following sections reference the CodingEvents MVC project we’ve been creating over the last several lessons to illustrate the capabilities of an alternative CodingEvents API project.

Shapes

Shape describes the input or output of an API in terms of its fields and data types. There are no rules for how shapes should be defined. However, the goal should be to describe shapes in a way that is easy to understand. For this reason, shapes are typically shown in a way that is similar to the representation format. Because we use JSON as the representation format, the JSON data types are used.

You can think of shape like a class definition in an object-oriented codebase:

1
2
3
4
5
6

public class CodingEvent {
    public int Id { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public DateTime Date { get; set; }
}

1
2
3
4
5
6

CodingEvent {
    Id: integer
    Title: string
    Description: string
    Date: string (ISO 8601 date format)
}

The JSON representation of the resource that the API sends out is then based on the shape. This is like how an object is based on the blueprint of its class.

Here’s a CodingEvent JSON Representation:

1
2
3
4
5
6

{
    "Id": 1,
    "Title": "Halloween Hackathon!",
    "Description": "A gathering of nerdy ghouls to work on GitHub Hacktoberfest contributions",
    "Date": "2020-10-31"
}

We can think of inputs as a partial state provided by the client during create and update operations. Only some of the fields are included because the API is responsible for providing the others.

Consider the following example of an input shape used to create an event. Notice that the Id field is not included:

1
2
3
4
5

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

Some of the common fields the API is responsible for managing:

• the unique identifier (Id)
• the “created on” or “last updated” timestamp
• links for relationships between resources

Endpoints

An API endpoint refers to the HTTP path and method that defines the location of a resource and the action to take on its state.

Endpoints are what an API exposes to its consumers. Each endpoint is made up of two components:

• path: the noun that identifies the resource
• method: the verb, or action, to take on the resource’s state

Identifying the Resource

Paths are used to identify the resource being interacted with. 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.

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

The name of the path is arbitrary but should follow these rules of thumb to maintain consistency:

• is lowercase and separated by underscores if necessary
• adequately describes the resource in as few characters as necessary
• is a plural noun (actions are described by the method of the endpoint)

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

1
2
3
4

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

1
2
3
4

[
    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.

1
2
3
4
5
6

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

CRUD Operations & HTTP Methods

As we saw in the previous article, state is something that can be interacted with 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.

Endpoint Behavior

Depending on the endpoint, the effect of a request can differ. In other words, the behavior of an endpoint is dependent on the subject – an entity or the collection as a whole.

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.

1
2
3
4
5

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

Operating On Entities

When removing a resource, the client is requesting a transition to an empty state. This means that both the request body 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:

Headers & Status Codes

A RESTful API uses HTTP response status codes and HTTP request and response headers. Response status codes inform the client if their request is handled successfully or if changes are needed to fix a request.

HTTP headers are used to communicate additional information (metadata) about a request or response. Let’s take a look at the status codes now.

Status Codes

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

Success Status Codes

When a request is successful, the 2XX status codes are used. These codes communicate to the consumer the type of success relative to the action that was taken. Below is a list of the common success codes you will encounter:

Common client success status codes for each action:

.. list-table:: Common client success status codes for each action :header-rows: 1 :widths: 20 20 20 40

Failure Status Codes

Requests can fail. Status code groups categorize two types of failure:

• client error: 4XX status code group
• server error: 5XX status code group

Client errors indicate that a request can be reissued with corrections. Each of these status codes and messages notify the consumer of the changes needed for a success. In contrast, server errors cannot be remedied by the client sending the request.

Let’s look at some of the common client error status codes:

A bad request will include an error message in its response. The message should indicate what the client must change in their request body to succeed. This failure is seen when creating or updating a resource entity:

1
2
3

{
    "Title": "Foo"
}

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

Headers

In RESTful design, HTTP headers communicate metadata about each interaction with a resource.

Common request/response headers in REST:

Learning More

These articles have covered the fundamental aspects of the RESTful mental model and practical usage. However, RESTful design is a deep topic that even extends beyond the web and use of HTTP!

If you want to learn more, the following links are a good start:

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)

Deep Understanding

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

Check Your Understanding