13 Best Practices for Building RESTful APIs

Facebook, GitHub, Google, and many other giants need a way to serve and consume data. A RESTful API is still one of the best choices in today’s dev landscape to serve and consume data.

But have you ever considered learning about industry standards? What are the best practices for designing a RESTful API? In theory, anyone can quickly spin up a data API in less than five minutes — whether it be Node.js, Golang, or Python.

We’ll explore 13 best practices you should consider when building a RESTful API. But first, let’s clarify a RESTful API quickly.

What is a RESTful API?

A RESTful API needs to meet the following constraints for it to be called a RESTful API.

1. Client-server: A RESTful API follows the client-server model where the server serves data and clients connect to the server to consume data. The interaction between client and server occurs through HTTP(S) requests that transfer the requested data.

2. Stateless: More importantly, a RESTful API should be stateless. Each request is treated as a standalone request. The server should not keep track of any internal state that might influence the result of future requests.

3. Uniform interface: Lastly, uniformity defines how the client and server interact. RESTful APIs define best practices for naming resources but define fixed HTTP operations that allow you to modify/interact with resources. The following HTTP operations can be accessed in RESTful APIs:

   • GET request: retrieve a resource
   • POST request: create a resource or send information to the API
   • PUT request: create or replace a resource
   • PATCH request: update an existing resource
   • DELETE request: delete a resource

With this deeper understanding of the characteristics of a RESTful API, it’s time to learn more about RESTful API best practices.

Best Practices For Designing Your First RESTful API

This article presents you with an actionable list of 13 best practices. Let’s explore!

1. Use HTTP methods correctly

We’ve already discussed the possible HTTP methods you can use to modify resources: GET, POST, PUT, PATCH, and DELETE.

Still, many developers tend to abuse GET and POST, or PUT and PATCH. Often, we see developers use a POST request to retrieve data. Furthermore, we see developers use a PUT request which replaces the resource while they only wanted to update a single field for that resource.

Make sure to use the correct HTTP method as this will add a lot of confusion for developers using your RESTful API. It’s better to stick to the intended guidelines.

2. Naming conventions

Understanding the RESTful API naming conventions will help you a lot with designing your API in an organized manner. Design a RESTful API according to the resources you serve.

For example, your API manages authors and books (yes, a classic example). Now, we want to add a new author or access an author with ID 3. You could design the following routes to serve this purpose:

• api.com/addNewAuthor
• api.com/getAuthorByID/3

Imagine an API that hosts many resources that each have many properties. The list of possible endpoints will become endless and not very user-friendly. So we need a more organized and standardized way of designing API endpoints.

RESTful API best practices describe that an endpoint should start with the resource name, while the HTTP operation describes the action. Now we get:

• POST api.com/authors
• GET api.com/authors/3

What if we want to access all books author with ID 3 has ever written? Also for this case, RESTful APIs have a solution:

• GET api.com/authors/3/books

Lastly, what if you want to delete a book with ID 5 for an author with ID 3. Again, let’s follow the same structured approach to form the following endpoint:

• DELETE api.com/authors/3/books/5

In short, make use of HTTP operations and the structured way of resource mapping to form a readable and understandable endpoint path. The big advantage of this approach is that every developer understands how RESTful APIs are designed and they can immediately use the API without having to read your documentation on each endpoint.

3. Use plural resources

Resources should always use their plural form. Why? Imagine you want to retrieve all authors. Therefore, you would call the following endpoint: GET api.com/authors.

When you read the request, you can’t tell if the API response will contain only one or all authors. For that reason, API endpoints should use plural resources.

4. Correct use of status codes

Status codes aren’t here just for fun. They have a clear purpose. A status code notifies the client about the success of its request.

The most common status code categories include:

Continue reading 13 Best Practices for Building RESTful APIs on SitePoint.