APIs are the most common types of web services we have today. They make it possible for clients such as browser applications to communicate with servers seamlessly. This makes it very important to design them properly to avoid problems along the way. If not, an API that is not properly designed will create problems for clients that use the API.
There are conventions that are commonly accepted that when used, will make sure that an API does exactly what it is supposed to do. This will also make using the API easier for everyone and avoid distracting people from using it.
Here are some of the common API design problems:
1. Using Lengthy or Wrong Names for Parameters
You might find an API that uses a precise parameter name that includes resources like the project ID. This is a common problem that should be avoided at all costs. The URI should have the resource, such as the project. Therefore, you should not have resources such as project_id but just id.
When it comes to lengthy names, it is better to use a dash between the names, for example, student-num. However, try as much as you can to avoid them. You can simply add a description of them on the API documentation.
2. Body in GET Requests
There are developers who add parameters in a URI. This is wrong. Parameters should always be added inside the body. You use the HTTP GET method for writing. The URIs do not identify a resource but an operation that one would like to perform on the resource.
3. Ignoring Caching
Do not ignore caching when designing your APIs. Well, it is easy to ignore caching by simply adding the header “Cache-control: no-cache”. However, HTTP has powerful caching mechanisms that have the If-Modified-Since header, 304 Not Modified response code, and ETag header. These mechanisms make it possible for servers and clients to always get a fresh copy of the resource. Caching also increases the performance and scalability of the API. The ETag response header allows you to cache unchanged resources.
4. Defining Error Codes and Error Messages
Most API developers make a mistake when implementing error handling. You will find that in most APIs, all requests return a response code of 200, even when it’s an error. This way, you will not be able to differentiate between unsuccessful or successful responses not unless you parse the body and check if there is an error or error code field. The RFC 7807 standard has detailed the correct way for developers to handle errors when designing APIs.
5. Long Response Times and Returning too Much Data
Developers tend to forget that the resources they return when they start building their APIs can increase in size and count. As time goes by, this causes their APIs to be under a high load that in return increases the response time of the APIs.
It is common sense that no one will want to use an API and sits longer waiting for a response after calling it. To avoid this, developers are encouraged to design their APIs with support for filtering, sorting, and pagination.
READ NEXT: The Main Differences in API Security Standards
If you design your API paying attention to the above common mistakes that developers make, you can be assured that your API will do its job well, and the API consumers will not face problems when using it.
