API is an acronym for “Application Programming Interface. APIs are significantly used in the software development world to exchange data between two applications. In other words, APIs allow applications to communicate with each other by sending and receiving data through an endpoint.
As an example, many applications integrate Facebook and Google login API to ease new and existing users onboarding into their application. Another example is Uber implementing Google Maps API rather than developing a new map application for its navigation system. Besides, frontend applications communicate with the backend application with the help of APIs
Developing APIs with the right structure and best practices enable other developers to easily integrate your application without hassles and it also ensures that you don’t allow attackers to have access to your backend application.
With all that said, let’s talk about the best practices in developing your APIs for effective usage and making them secure.
- Use the right HTTP verbs
- Use the right status codes
- Return error details in response
- API versioning
- Validate all requests
- Validate all user input
- Document your APIs
- Secure your APIs
1. Use the right HTTP verbs
This include (GET, POST, PUT, PATCH, DELETE)
HTTP GET – This is used to retrieve data resources only and not to modify. In other words, a GET request should not be used to create or update a resource.
Bad example
GET /get-all-articles GET /FetchUsers
Good Example
GET /articles GET /users
HTTP POST – This is used to create new data resources
Bad example
POST /create-new-article GET /add-new-user
Good Example
POST /articles POST /users
HTTP PUT – This is used to update or replace the content of an existing resource
Bad example
POST /update-article/:id
Good Example
PUT /articles/:id
HTTP PATCH – This is used to partially update the content of an existing resource. The difference between PUT and PATCH verb is that PUT is used when you want to completely update the resource while PATCH is used when you want to partially update a resource
Bad example
POST /update-article/:id GET /update-user/:id
Good Example
PATCH /articles/:id PATCH /users/:id
HTTP DELETE – This is used to delete resources
Bad example
GET /delete-article/:id
Good Example
DELETE /articles/:id
Using the right HTTP Verb makes the user of the API understands what the API will do. The above examples show a better representation of using the HTTP verbs in the right manner
2. Use the right status codes
The most common HTTP status codes include (200, 201, 202, 204, 400, 401, 403, 500).
200 (OK)
This indicates that the request was completed and successful. This is used when the other status codes in the 2xx series are inappropriate. Unlike the 204 status code, the 200 status code should include a response in its body.
201 (CREATED)
This is used when a resource has been fulfilled and creates new data in return.
202 (ACCEPTED)
This is used when the request in a resource has been accepted for processing but it is not completed yet. The request may or may not eventually be acted upon, as it may be disallowed when processing actually takes place. there is no facility for status returns from asynchronous operations such as this.
204 (NO CONTENT)
This is an indication that the server has fulfilled the request and there is no information to send back.
400 (BAD REQUEST)
This is used when the request could not be understood by the server due to malformed syntax, invalid request message parameters, or deceptive request routing.
401 (UNAUTHORIZED)
This is an indication that the client is trying to access a resource that is protected without including the proper authorization
403 (FORBIDDEN)
This is used when the client is authenticated but isn’t authorized to perform the requested operation on the given resource.
500 (INTERNAL SERVER ERROR)
This is when the server encountered an unexpected condition which prevented the resource from fulfilling the request.
3. Return error details in response
When an API returns an error, it is not enough to return the status code nor status code with a generic error message such as (Server error – An error just occurred), it is necessary that an error returned from an API is detailed as possible. A detailed error helps the API consumer in debugging and to understand what is going on
4. API versioning
API versioning is very important in API development. It allows you to incorporate the latest changes in a new version of your API thereby still allowing users to have access to the older version of your API without breaking your users’ application.
api/v1/articles api/v2/articles
5. Validate All Requests
It is important that every API request is validated to ensure that the client has the authorization to access the data request. UserA should not have access to the data of UserB except UserA have the permission to access the data
6. Validate All User Input
It is necessary that APIs that contain data in its body is validated before it is being processed in the backend. For example, a user login API will include email and password in its API body, it is important that the data is validated and no other malicious or invalid data is sent along with the API.
Note that, before processing any data from your API, validate that the data is in the format you are expecting.
7. Document your APIs
Documenting your APIs is really important because it allows the users of your API
- to have a basic understanding of what the APIs do,
- the data to include in its request, and
- the type of response to expect.
Every developer loves good documentation because it makes their work easier. Postman is a very good tool for creating documentation for your APIs
8. Secure your APIs
The security of your API is very important to your application. Having a vulnerability in your API can enable an attacker to have access to your application and perform different exploits.
Below are the following ways to protect your APIs and ensure they are well secured
- Ensure you don’t store sensitive information in your Authentication tokens.
- Use SSL for your APIs
- Validate all inputs and requests
- Ensure you encrypt all sensitive information stored in your database.
- Enforce a limit to the number of API requests within a timeframe, this is called Rate Limiting or API throttling. Incorporating API throttling can protect you against Brute Force/DDoS attacks
- Don’t pass sensitive data in your API, for example, https://example.com/login/username=jack&password=12345
We should all strive to develop APIs that are easy to use and integrate into applications. I hope this article has been able to help you with developing APIs that are a delight to use.
Cheers!!!
