REST APIs are the primary form of web services, used widely to power websites, mobile applications, and most enterprise integrations. For a technology that is so ubiquitous, there is still confusion around REST standards. Compared to the previous generation of web services, namely SOAP, there is much more flexibility with how companies approach REST. However, there are still best practices and guidelines to consider.

In this post, we’ll cover the REST architectural style (REST is not a standard), some REST API design conventions, and introduce a standard related to REST that can bring a standard-like rigor to your APIs.

REST is an Architecture, Not a Standard

REST, which stands for REpresentational State Transfer, was introduced by Roy Fielding in his 2000 dissertation. While Fielding described REST outside of HTTP, it was developed alongside the protocol and is most commonly used over HTTP. While HTTP is a standard, REST itself is not. Rather, it’s an architectural style that provides constraints which guide API design.

Many APIs do not conform to every element of REST, which has caused some to use the term RESTful or even HTTP APIs to describe the most common types of APIs. Commonly-adopted principles of REST include:

  • Client-server separation: the client determines how responses are displayed to the user, allowing the server to parse the request and produce the response.
  • Stateless requests: the server does not have to store any context between requests—everything needed is within each request.
  • Resource identifiers: the interface is designed around resources that are identified by URLs.

These criteria are present in most modern REST APIs. You can read more details in the dissertation, but we’ll focus in the next sections on practical applications of REST in API design.

REST API Design Guidelines and Conventions

While REST is not a standard, there are some guidelines and conventions that have been widely adopted. These include building atop HTTP’s standards, naming resources as nouns, and popular data formats.

HTTP Methods

Web developers are likely familiar with GET and POST, along with the other HTTP methods, also sometimes called HTTP verbs. These methods define the type of request being made to a REST API.

Common HTTP methods include:

  • GET: retrieve data, the equivalent to a read in CRUD APIs
  • POST: add new data
  • PUT: update existing data
  • PATCH: update a subset of existing data
  • DELETE: remove data

While there are other methods, they are rarely seen in REST APIs. The method itself does not mean much without the target, the resource.

Resource Names

Resources are sometimes referred to as the nouns that the HTTP verbs act upon. Earlier web services were built around remote procedure calls, which saw APIs as extensions of the code that called them. By contrast, REST resources can be accessed with multiple HTTP methods, which makes them less analogous to a procedure call.

For example, if your API stored animals, a resource name might be “animals.” And the path to access that resource might be /api/animals. The resource would then be combined with HTTP methods like so:

  • GET /api/animals: retrieve a list of animals
  • POST /api/animals: add a new animal
  • GET /api/animals/cat: retrieve a single animal by ID
  • PUT /api/animals/cat: update a single animal by ID
  • DELETE /api/animals/cat: delete an animal by ID

Identifiers might be integers, hashes, or other value that is auto-generated. Whether resources are plural or singular is a matter of preference (and hotly debated). Most importantly, remain consistent within your API and across multiple APIs in the same organization.

Data Formats

Most API requests will return content from the server that the client needs to interpret. Rarely is this content plain text—usually, it will use a particular format. While REST does not define any data formats, JSON and XML are the two most common.

A single result in JSON might look like this:

  "id": "cat",
  "name": "House cat",
  "genus": "Felis",
  "img": ""

While the same data in XML could be represented like this:

<?xml version="1.0" encoding="UTF-8" ?>
  <name>House cat</name>

Similar structures would be used in the body of requests when passing data, such as with POST, PUT, or PATCH requests. Typically, request and response bodies use the same data format.

Other common formats include: CSV, HTML, RSS, and YAML.

HTTP Statuses

Since REST APIs depend upon HTTP standards, each request’s status is used to communicate the result of the request, such as success or failure. Each status code provides a machine-readable response, plus a human-readable message. Web developers (and a number of users) will be familiar with many of these.

  • 200: Success
  • 201: Created
  • 404: Not found
  • 401: Unauthorized
  • 403: Forbidden
  • 429: Too many requests

There are more, of course, including 300-level redirection and 500-level server errors. You’ll want to use the right status code for the appropriate situation as you design your REST API.

OpenAPI Lets You Set Your Own “Standard”

While REST is not a standard, there are many other standards often associated with REST. For example, OAuth covers third-party authorization for resources and JSON PATCH describes a standard approach to the HTTP PATCH method for the JSON data format. An important standard as you design your own APIs is the OpenAPI specification.

OpenAPI is a standard to describe REST APIs and it allows you to declare your API security method, endpoints, request/response data, and HTTP status messages. Together, these define decisions about your own API. These are useful during the design phase, but can also be useful throughout the API lifecycle.

Create OpenAPI documents now using a visual editor, or bring in an existing repository. Help define the API standard for your organization to create consistent, developer-friendly APIs.

Photo by Mendar Bouchali

Peek-a-Boo (1)

Subscribe for the latest in API Design

By submitting this you will be receiving our latest updates on post.

Take a Listen to API Intersection

The podcast on the intersection between API design & digital transformation

Related Posts