- April 25, 2023
- For programmers
REST API Best Practices


A REST API's construction differs significantly from a standard application's. An API is an application programming interface that allows different programmes to communicate with each other.
There are different types of API construction, such as REST API or GraphQL. The most common type is a REST API, sometimes called a RESTful API, which is one that has defined access points.
See 6 Best Practices in programming REST API.
What is the REST API
A REST API is a type of API that has defined so-called endpoints, i.e. points that accept the corresponding input and return the output in a defined form. APIs can be divided into two types:
- public - any person meeting certain conditions can have access, an example of a public API would be the twitter API.
- private - an API that can only be accessed by developers within an organisation, such an API can be used for multiple programmes to communicate with each other.
The REST API has documentation that specifies what endpoints are available, what input they expect and what output will be returned in each situation.
JSON is the most common format for building APIs, but we can also encounter APIs that accept and return data in e.g. XML format.
HTTP Status Codes
When building a RESP API, getting the HTTP status software correct is very important. An HTTP status code is a number that tells us what type of request we are sending and what the API will return.
HTTP statuses are divided into:
- 1xx - Informational
- 2xx - Success
- 3xx - Redirection
- 4xx - Client Error
- 5xx - Server Error
The most popular codes:
- 200 - OK
- 201 - Created
- 301 - Moved Permanently
- 403 - Forbidden
- 404 - Not Found
- 405 - Method Not Allowed
- 408 - Request Timeout
- 429 - Too Many Requests
- 500 - Internal Server Error
- 502 - Bad Gateway
- 503 - Service Unavailable
- 504 - Gateway Timeout
HTTP methods
To make our API compliant with the standards, we need to handle the HTTP methods in the requests sent to the API.
To understand this concept, let's assume an example of a simple API in which we have endpoints to receive a list of users, retrieve a user by ID, create a user, and edit deleting a user. If we did not include HTTP statuses, we would have to create 5 endpoints, each with a different URL:
- /users/list
- /users/user/{id}
- /users/create
- /users/update
- /users/delete
However, if we want to make our API according to standards, we should only have one URL - /users - with an optional parameter - ID - but our code should handle specific actions depending on the HTTP method the request is sent by.
- GET /users - List of all users
- GET /users/{id} - Retrieve user by ID
- POST /users - Create user
- PUT /users/{id} - Edit user
- DELTE /users/{id} - Delete user
In the example above, each of these requests has the same address (not counting the ID parameter), but it is the HTTP status that defines what exactly the API should do.
Example:
curl -X GET -H "Accept: application/json" https://api.example.com/users/1
Output format
When creating an API, it is very important that the output that is returned always has a standardised format. There is nothing worse for a programmer working with an API than having to check each time what form the data will be received in. The returned output, should immediately say what the status of the operation is and return all possible data that is available for this request.
Additionally, with outputs, as with requests, the HTTP status is also very important. For example, if a user tries to send an unauthorised request and we return an error, we would not return the error with the code 2XX but return it with the code 401, i.e. Unauthorised.
Example:
200 {
“type”: “success”,
“status”: 200,
“data”: {...}
}
or
404 {
“type”: “error”,
“status”: 404,
“message”: “User doesn't exist”
}
Handling Errors
Error handling in the REST API is just as important, if not more so, than in standard applications. The difference is that errors in the REST API will not be seen on the browser screen. Standard applications can be accessed by a URL that someone can send us so that we can verify them easily. In the case of the REST API, we can reproduce the request, but this is more complicated because we have to authorise the request and provide exactly the same input. Therefore, it is important that our API has good error handling right from the start, which not only catches all problems but also notifies us when an error occurs.
REST API Performance
In general, applications using the API operate in synchronous mode. It is a mode that, simply put, works in such a way that when sending a request the application waits for a return from the API. The more time the API needs, the slower the application will operate. This is why it is so important to analyse and improve the performance of REST APIs.
Track end points
As I mentioned earlier, each REST API consists of certain endpoints, which differ in address and HTTP method. It is worth implementing a solution that allows all endpoints to be analysed, not only for errors or performance but also for consumption, unauthorised access attempts or analysis of how users use our API.
Important! If you are creating or developing an API, be sure to see our tool. Streply allows you not only to catch errors but also to handle logs, measure API loading times or analyse user behaviour.
Create an account, test Streply entirely free for 30 days, and then pay only 9$ per month.

Pricing
You only pay for what you use
Monthly usage
100k requests
Logs retention
14 days
Price
9$ per month
Monthly usage
500k requests
Logs retention
30 days
Price
24$ per month
Monthly usage
1M requests
Logs retention
60 days
Price
49$ per month
Monthly usage
5M requests
Logs retention
90 days
Price
99$ per month
Monthly usage
10M requests
Logs retention
180 days
Price
149$ per month
Monthly usage
+10M requests
Logs retention
360 days
Price
negotiable
Monthly usage
100k requests
Logs retention
14 days
Price
90$ per year
Monthly usage
500k requests
Logs retention
30 days
Price
240$ per year
Monthly usage
1M requests
Logs retention
60 days
Price
490$ per year
Monthly usage
5M requests
Logs retention
90 days
Price
990$ per year
Monthly usage
10M requests
Logs retention
180 days
Price
1490$ per year
Monthly usage
+10M requests
Logs retention
360 days
Price
negotiable
- Free 30-days trial
- No credit card required
- Cancel anytime
