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:

Example
public class Event {
    public int id;
    public string name;
    public string description;
}

...getters

...setters

The output resource shape of an Event entity:

Event {
    id: integer
    name: string
    description: string
}

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 an Event JSON Representation:

Example
1
2
3
4
5
{
    "id": 1,
    "name": "Halloween Hackathon!",
    "description": "A gathering of nerdy ghouls to work on GitHub Hacktoberfest contributions",
}

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:

Example
1
2
3
4
Event {
    name: string
    description: string
}

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:

Example

The codingevents API would have the following familiar resources (among others):

ResourcePath
Coding Event/events
Tag/tags

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:

Example

Here is a response from a request to the GET /events endpoint:

1
2
3
4
[
    CodingEvent { ... },
    ...
]

The state of the CodingEvent collection is made up of the collective state of each CodingEvent entity within it.

Example

Here is a response from a request to the GET /tags endpoint:

1
2
3
4
[
    Tag { ... },
    ...
]

A request to the endpoint of the Tag collection would include its respective Tag entity representations (JSON objects).

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.

Tip

The hierarchy of collections and entities is similar to directories and files. To identify an entity is like identifying a file within a directory. You need both the directory (collection) name and a sub-path that uniquely identifies the file (entity).

Example

The generic path to identify a CodingEvent resource is noted as /events/{codingEventId}.

Let’s assume a CodingEvent entity exists with an id of 12.

We could make a request to the GET /events/12 endpoint to read its current state and receive this response:

1
2
3
4
5
{
    "id": 12,
    "name": "Halloween Hackathon!",
    "description": "A gathering of nerdy ghouls...",
}

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:

HTTP MethodCRUD Operation
POSTCreate
GETRead
PUT/PATCHUpdate
DELETEDelete

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.

Note

If a client tries to take an action on a resource that is not supported by the API, they will receive a 405 status code or Method not allowed error response.

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

HTTP MethodBehavior with resource state
POSTcreate a new entity in the collection
GETview the current list of all entities in the collection
PUT/PATCHbulk update of entities in the collection
DELETEremove all entities in the collection
Note

Exposing the ability to modify or delete all of the entities in a collection at once can be risky. In many cases, the design of a RESTful API will only support GET and POST endpoints for 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.

Example

As we saw earlier, the input shape for creating an event only includes the fields the consumer is responsible for. The Id field is then managed internally by the API.

We refer to this shape as a NewCodingEvent to distinguish it from the CodingEvent resource shape:

1
2
3
4
NewCodingEvent {
    name: string
    description: string
}

We can describe this request in a shorthand:

POST /events (NewCodingEvent) -> 201, CodingEvent

This shorthand includes:

  1. The endpoint method: POST
  2. The endpoint path: /events
  3. The name of the request body: (NewCodingEvent)
  4. The returned status code: 201
  5. The returned response body: CodingEvent

After sending this request, the response includes:

  • a 201, or Created, status code
  • a Location response header
  • the representation of the created resource entity state (including an assigned Id field)

Operating On Entities

HTTP MethodBehavior with resource state
POSTN/A (created inside a collection)
GETview the current entity state
PUT/PATCHupdate the entity state
DELETEremove the entity from the collection

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:

Example

Let’s once again assume a CodingEvent resource exists with an id of 12. If we want to remove this entity, we need to issue a request to its uniquely identified DELETE endpoint:

DELETE /events/12 -> 204

In this shorthand, you can see that this request has an empty request body. This is the empty state we are requesting a transition to. The 204, or No Content, status code in the response indicates that the action was successful and that the response body is empty. The API transfers back a representation of empty state (no response body) to the client.

Example

What would happen if we made another request to the endpoint of a resource entity that doesn’t exist, DELETE /events/999?

We would receive a404, or Not Found, status code that lets us know the request failed because of a client error (providing an id for a nonexistent resource).

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:

HTTP MethodStatus CodeMessageResponse
POST201CreatedResource entity and location header
GET200OKResource entity or collection
DELETE204No Contentempty response body

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:

Status CodeMessageCorrection
400Bad RequestClient must fix errors in their request body
401UnauthorizedClient must authenticate first
403ForbiddenAn Authenticated client in not allowed to perform the requested action
404Not FoundThe path to identify the resource is incorrect or the resource does not exist

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:

Example

In the upcoming SpringRestApiApplication, the state of a Event is validated using the following criteria:

  • name: “string text”
  • description: “string text”

Imagine a client sending a PATCH request to update the Event resource entity with an Id of 6.

PATCH /events/6 (PartialCodingEvent) -> CodingEvent

If their request body contains a name field that is empty, the request will receive a 400 status code:

Here is a portion of an invalid request to the PATCH /events/6 endpoint:

1
2
3
4
{
    "name":
    "description": "Event without a name"
}

name does not contain any content, making it an invalid Event name. The SpringRestApiApplication API response to such a request therefore includes a 400 status code. This alerts the client that they must correct their data representation. The response body indicates which aspects of the request are invalid.

Using the information in the response, the client can fix their request body and reissue the request successfully.

Note

The 401, or Unauthorized, status code actually indicates that the consumer is not authenticated. This means the consumer has not proven their identity to the API. The 403, or Forbidden, status code is a more accurate description of being unauthorized. After authenticating, the consumer’s authorization can determine if they are allowed or forbidden from taking the requested action.

Headers

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

Common request/response headers in REST:

Request/ResponseHeaderMeaningExample
BothContent-TypeThe attached body has the following media typeapplication/json
RequestAcceptThe client expects the requested resource representation in the given media typeapplication/json
ResponseLocationThe created resource representation can be found at the given URL value/resources/{id}
Tip

The Authorization request header is also commonly used.

Check Your Understanding

Question

A POST request performs which type of action?

  1. Create

  2. Read

  3. Update

  4. Delete

Question

The _________ portion of a RESTful URL identifies the resource.

  1. path

  2. query

  3. host

  4. user