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:

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:

or

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.

Are you ready to level up your PHP software?

Create an account, test Streply entirely free for 30 days, and then pay only 9$ per month.

Bugs

Logs

Performance

Try for free in 30 seconds

Share this post:

Michal Molenda
I'm a Streply owner and web applications developer with over 15 years of experience. Privately husband, father of 2, and digital nomad for almost 14 years.