Always will be ready notify the world about expectations as easy as possible: job change page
Jan 8

REST API design best practices

REST API design best practices

“Application Programming Interface” or API, refers to a communication channel between various software services. Applications that transmit requests and responses are called clients and servers, respectively.

There are different types of API protocols:

  • REST — relies on a client/server approach that separates the front and back ends of the API and provides considerable flexibility in development and implementation.
  • RPC — The remote procedural call (RPC) protocol sends multiple parameters and receives results.
  • SOAP — Supports a wide range of communication protocols found across the internet, such as HTTP, SMTP, and TCP.
  • WebSocket — Provides a way to exchange data between browser and server via a persistent connection.

What is an API?
What is an API?

Most of our daily work as software engineers utilizes or creates REST APIs. The standard method of communication between the systems is through APIs. Therefore, it’s crucial to build REST APIs properly to avoid issues in the future. A well-defined API should be easy to work with, concise, and hard to misuse.

Here are some general recommendations:

1. Use nouns instead of verbs

Verbs should not be used in endpoint paths. Instead, the pathname should contain the nouns that identify the object to which the endpoint we are accessing or altering belongs.

For example, instead of using /getAllClients to fetch all clients, use /clients.

2. Use plural resource nouns

Use the plural form for resource nouns because this fits all types of endpoints.

For example, instead of using /employee/:id/, use /employees/:id/.

3. Be consistent

When we say to be consistent, this means to be predictable. When we have one endpoint defined, others should behave similarly. So, use the same case for resources, the same auth methods for all endpoints, the same headers, the same status codes, etc.

4. Keep it simple

We should make naming all endpoints resource-oriented, as they are. If we want to define an API for users, we would describe it as: 



So, the first API gets all users, and the second one gets a specific user.

5. User proper status codes

This one is super important. There are many HTTP status codes, but we usually use just some. Don’t use too many, but use the same status codes for the same outcomes across the API, e.g.,

  • 200 for general success.
  • 201 for successful creation.
  • 202 for a successful request.
  • 204 for no content.
  • 307 for redirected content.
  • 400 for bad requests.
  • 401 for unauthorized requests.
  • 403 for missing permissions.
  • 404 for lacking resources.
  • 5xx for internal errors.

HTTP Status Codes
HTTP Status Codes

6. Don’t return plain text

REST APIs should accept JSON for request payload and respond with JSON because it is a standard for transferring data. Yet, it is not enough to return a body with JSON-formatted string; we need to specify a Content-Type header to be application/JSON. The only exception is if we’re trying to send and receive files between the client and server.

7. Do proper error handling

Here, we want to eliminate any confusion when an error occurs. We must handle errors properly and return a response code indicating what happened (from 400 to 5xx errors). We need to return some details in the response body along with a status code.

8. Have good security practices

We want all communication between a client and a server to be protected, meaning we need to always use SSL/TLS, with no exceptions. Also, allow authentication via API keys, which should be passed using a custom HTTP header with an expiration date.

9. Use pagination

Use pagination if our API needs to return a lot of data, as this will make our API future-proof. Use page and page_size is recommended here.

For example, /products?page=10&page_size=20

10. Versioning

It is essential to version APIs from the first version, as our APIs could have different users. This will allow our users to avoid being affected by changes that we can make in the future. API versions can be passed through HTTP headers or query/path params.

For example, /products/v1/4

Also, don’t forget to document your APIs because API will be only as good as its documentation. The docs should show examples of complete request/response cycles. Here, we can use the OpenAPI definition as a source of truth.

To develop APIs, check Swagger and OpenAPI specifications, Postman, or Stoplight.

Thanks for reading, and stay awesome!

• • •

Originally published at on February 9, 2023.

May 5
Author: C# Programming Obinna “Anderson” Asiegbulam
IntroductionOpen Data Protocol (OData) is a standard protocol for building and consuming RESTful APIs. It extends traditional REST-based data access techniques by providing a uniform way to expose, structure, and manipulate data. Originally developed by Microsoft, OData is widely adopted...
Feb 6, 2023
Author: Sajal Soni
In this tutorial, I'll teach you how to build a simple REST API with PHP and MySQL.REST has become the de facto standard when it comes to exposing data via APIs and building web services. In fact, most web applications...
Jan 18, 2023
Author: Jay
Aha! There is always something intimidating about Dependency Injection. I distinctly remember a couple of years ago, telling a .Net recruiter for a contract project, that,“I had no idea what DI is”He immediately stopped talking to me. It’s just one...
Mar 18
Author: codezone
File reading operations in C# are crucial for many applications, often requiring efficiency and optimal performance. When handling file reading tasks, employing the right strategies can significantly impact the speed and resource utilization of your application. Here are some best...
Send message
Your name

© 1999–2024 WebDynamics
1980–... Sergey Drozdov
Area of interests: .NET Framework | .NET Core | C# | ASP.NET | Windows Forms | WPF | HTML5 | CSS3 | jQuery | AJAX | Angular | React | MS SQL Server | Transact-SQL | ADO.NET | Entity Framework | IIS | OOP | OOA | OOD | WCF | WPF | MSMQ | MVC | MVP | MVVM | Design Patterns | Enterprise Architecture | Scrum | Kanban