When developing a mobile or cloud app, creating automated business processes, or making an app that is front and backend divided, we will probably write a REST API. In a few words, REST API is a set of functions with which developers can perform requests and receive responses via HTTP protocol such as GET and POST. Digging deeper, developers learn about HTTP methods purposes and message formats. They focus on how to provide and process data, forgetting, that their API will be actually used by other developers and their application users. In this article I will describe what usually tends to be overlooked by people who develop an API, but is important for those who will use it.
#1 Error reporting
Error responses are as important as success ones. They affect applications that use our API – on the basis of errors developers change program behaviors and provide information to users. Due to the above, error responses should be consistent and thought out. Being aware of common mistakes will improve their usability:
- Developers often forget about the diversity of HTTP status codes, limiting themselves to return 0 when error occurs. Expanding the range, we can for example tell, that a client is unauthorized by returning a 401 status code – on this basis a developer who uses our API can redirect the user to the login page. Returning 403 means that access is forbidden – , the developer may then give the user the opportunity to ask for access for this resource. For more information about status codes see HTTP Status Codes Registry
- Making messages ‘human’ understandable is also important. It should summarize the context and cause. Giving general solution to handle the error also can be handy.
#2 Documentation
Remembering that your direct customers are developers, you should assist them in learning how to use your service. Remember, employees change and memory is fleeting, so write documentation. An additional benefit is that it helps to spot inconsistencies in the application. There is a bunch of ready made solutions that will simplify this job, like Swagger, NelmioApiDoc or RAML.
#3 Validation
Almost all programmers remember to validate important data – unfortunately, this is not enough. All input data should be validated, as during your API life, someone will inevitability find a gap and/or break something at some point (usually unattended).
For example, if we have a non-obligatory field, that should contain an amount of something, it is highly possible that leaving it without validation will break something when the user sends an empty value.
#4 Scalability
Scalability is something that we usually forget, until it becomes a big problem. As the number of our API customers grow, gaining data and running processes can take more time and may not always be available. Scalability issues affect all customers and can cause increasing dissatisfaction over time. When developers are not prepared to scale, it can take a lot of time and effort to sort things out. If while developing an API programmers keep in mind, that someday the number of its customers will grow, they can make wiser decisions. Selecting a scalable database and web server, and separating all application layers on independent scalable servers is a good start. But, developers should always be aware that their decisions now should not prevent scaling later. For example, when we decide to collect images sent by users, it is tempting (quick and easy) to keep them directly on a web server. The difficulty comes when the application grows and there is a need to use two or more web servers behind a load balancer. An easy solution is file synchronization over servers, but this always cause problems and delays. What should be done at the beginning is to upload files in a dedicated shared file storage location or any other remote storage.
#5 Time consuming
Customers expect quick responses for their requests. Unfortunately, time-consuming actions often stand in the way. Sending emails or scaling uploaded photos during the request are common pitfalls to fall in to. To avoid them, there is one important rule to follow: time or processor consuming actions should be delegated to an external process, so HTTP requests can be released as soon as possible.
