There is more to REST APIs than spitting out json or XML output to a client request. A good API should be predictable and easy to use. The success of your API depends on how many and what developers can do with your API. Even if you write APIs for personal use you will still benefit from following the guidelines recommended in this article. Let’s say you have a server with a rich collection of resources i.e. customer data, photos, videos etc that you would like to share with other developers, allow them to modify or delete the resources, and allow them to create new ones. In a nutshell, you need to design an API that supports Create, Read, Update, and Delete functions. Let’s very tempting to create URLs such as;
  • api.mysite.com/createCustomer
  • api.mysite.com/readCustomer
  • api.mysite.com/updateCustomer
  • api.mysite.com/deleteCustomer
rest_api_design_best_practices

Best Practice # 1: Use HTTP VERBS to determine action to be taken

While the above approach works just fine, there is a better and professional way of doing the same. You can use the resource (customer) and take advantage of HTTP verbs to determine the action that should be taken. The following table shows the professional and improved way of implementing the above example
HTTP VERB GETPOSTPUTDELETE
ResourceURL
customerapi.mysite/customersList customersCreate new customer

Update existing customer

Delete existing customer
  The second implementation will provide only a single URI to interact with the resource. The action will be determined based on the HTTP VERB from the client requesting for the resource

Best Practice Number 2: API Versioning

Remember the API will be used by other programs. What if we want to drop certain fields from the customer resource or modify the output and the way resources are created. We can update the code on the server but that will break the applications of your clients that consume the API. This is when API versioning comes in handy. It is recommended to use whole numbers and not numbers with decimal points. Our above URL when versioning is considered will look as follows
api.mysite/v1/customers
When we make changes in the future, we can simply add a new URL that may extend the controller class for v1 and get something like the URL shown below.
api.mysite/v2/customers
With the above approach, you can roll out new versions of your API without breaking existing applications that rely on earlier versions of the API

Best Practice # 3: Use plurals to describe resources

Suppose we want to retrieve only a single customer from the API using the customer id, we can use the following URL
api.mysite/v1/customer/1234
Suppose we want to retrieve all the customers, we can use the following URL
api.mysite/v1/customers
Note the second URL uses a plural while the first one uses a singular. From a grammatical point of view it makes sense but breaks consistency in your URLs. Consider the following URLs
api.mysite/v1/customers/1234
api.mysite/v1/customers
The base URL is exactly the same. The difference is the other one has a parameter while the second one doesn’t. Designing your APIs like this will make it easier for other developers to use.

Best Practice # 4: Use query strings to build relations

Your API will provide access to more than one resource and they will most likely be related. Suppose you have customers as resources, the customers will have orders made and you will probably have employees responsible for the customers. You may want to get the details of the employee who handled a particular order or customers who made orders in the year 2013 with quantities greater than 5 for the product Samsung Galaxy. As you can see, getting such details becomes very complex as they are too many combinations of criterion Consider the following URL
api.mysite/employees /orders/year/2013/greaterthan/5/Samsung
The above URL is permanent and if all possible combinations were to be imagined, we would come up with a lot of URLs for our API. With query strings, the above URL would look as follows
api.mysite/employees/orders?year=2013&quantity=>5&product=Samsung
The second URL only references the employees and orders resources. The complexity has been included using query strings. The advantage of this approach is that it is flexibility. Your API users only need to know employees/orders and can come up with any combination of valid query parameters depending on their application needs.

Best Practice # 5: Partial responses

Every time that your API is consumed by a client, bandwidth is consumed. On the client side, enough memory is also required to hold the returned resources. Most APIs are consumed from smart phones and not all of them have large memory. Partial responses allow you to return only necessary data and save on bandwidth. Let’s consider the example of employees. An employee will probably have lots of data i.e. contact number, email address, postal and physical address, department etc. what if we are only interested in the employee name, and email address? It would be pointless to include the other fields in the response. Consider the following URL
api.mysite/employees/123?fields=name,email
It will retrieve the employee record with id 123 and only return the name and email address of the employee.

Best Practice # 6: Response Codes and Error Handling

HTTP status codes will simplify giving feedback to your API users. The following table shows some of the most common response codes
HTTP Status CodeDescription
200 (OK)Response to HTTP VERB is successful
201 (Resource Created)Used with POST HTTP VERB that results in creating a new resource on the server
204 (No Content Return)Ideal when dealing with a VERB like DELETE
206 (Partial Content)Ideal for partial responses
401 (Unauthorized)If the client login failed
404 (Not Found)When then client requests for a resource that does not exist
429 (Too many requests)When the client sends too many requests
For a complete list of status codes, check this link

Best Practice # 7: Limit the number of request in a given time period from the same IP Address

If it’s exposed to the public online then it is a target for spam, bots and abuse. You can limit to request made per second to say may be 5. Anything more than that may be an indicated of automated programs abusing your API

Best Practice # 8: Consider Banning requests based on IP Address

They may be times when you have to make the difficult decision of banning requests from certain IP addresses based on suspicious behavior. This will protect your legitimate users when your API is under attack

Best Practice # 8: use json as the default

This may be subjective but if numbers on those who agree with json as the default are anything to go by then consider it as the default if no output format has been specified.

Best Practice # 9: Use OAuth latest version for authentication

This one too is subjective; take it as a quantitative best practice.

Best Practice # 10: Cache GET results for less frequently changing data

Caching will dramatically improve the performance of your API

Summary

A good API can be among a company’s greatest assets, a bad API can be among a company’s greatest liability (Joshua Bloch). The 10 above best practices if followed will make life easy for the developers that use your API. A usable API may just turn you into the next millionaire. We will be building be building a RESTful API that takes the above best practices into considering. The tutorials will be published on a weekly basis and will be implemented in Java, C# and PHP. Subscribe to our newsletter (provided at the bottom of this post) to get weekly updates on new content.