REST API Design Standards: Do They Even Exist?

For a technology that is so ubiquitous, there is still confusion around REST standards. REST APIs are the primary form of web services, used widely to power websites, mobile applications, and most enterprise integrations. Compared to the previous generation of web services, namely SOAP and XML-RPC, there is much more flexibility in how companies create RESTful web services. This is because REST was developed to work in a large variety of environments, with multiple data types. Implementing a REST API is versatile, but there are still best practices and guidelines to consider.

In this post, we’ll cover the REST API architectural style (REST itself is not a standard), some REST API design and naming conventions, and introduce a standard related to REST that can bring a standard-like rigor to your APIs. REST API design patterns do exist, and you can benefit by adopting them. Let’s dive into API REST architecture! 

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 that guide REST API design.

Many APIs do not conform to every element of REST, which has caused some to use the term RESTful to describe the most common types of APIs. Commonly-adopted principles of REST APIs 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 design patterns are present in most modern REST APIs. You can read more details in Fielding’s dissertation, but we’ll focus here on practical applications of REST in API design.

REST API Design Guidelines and Conventions

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

HTTP Methods and Examples

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

For example, if your API stored animals, a resource name might be “animals.” 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/dog : retrieve a single animal by ID
•  PUT /api/animals/dog : update a single animal by ID
•  DELETE /api/animals/dog : delete an animal by ID

Identifiers might be integers, hashes, or other values that are auto-generated. Whether resources are plural or singular is a matter of preference (and hotly debated). Most importantly, remain consistent within each API and across 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 structured data format. While REST does not specify any data formats, JSON and XML are the two most commonly used.

A single result from JSON API standards might look like this:

```
{
  "id": "dog",
  "name": "Pet dog",
  "genus": "Canis",
  "img": "https://cdn2.thedogapi.com/images/1MZ0YbOpS.jpg
"
}
```

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

```
<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <id>dog</id>
  <name>Domestic dog</name>
  <genus>Canis</genus>
  <img>https://cdn2.thedogapi.com/images/1MZ0YbOpS.jpg
</img>
</root>
```

Alternatively, in RSS it could be represented like this:

```
<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
<channel>
<title> dog</title>
<link>"https://cdn2.thedogapi.com/images/1MZ0YbOpS.jpg"</link>
<description>Pet dog</description>
</channel>
```

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, 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
• 401: Unauthorized
• 403: Forbidden
• 404: Not found
• 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 while JSON PATCH describes a standard approach to the HTTP PATCH method for the JSON data format. An important standard to keep in mind 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, design endpoints, request/response data, and HTTP status messages. Together, these define your API in a single document. These are useful during the design phase, but can also be useful throughout the API lifecycle. 

Create OpenAPI documents using a visual editor, or bring in an existing repository and use the graphical interface to make changes. REST API design standards exist to help all web developers create better, more functional, clearly communicated APIs. Help create definitions of the REST API standard for your organization and create consistent, developer-friendly APIs by defining your own, or learn more about design patterns for REST APIs.