Most of the applications are architected around RestAPIs these days, be it for layering or for integration. All leading web technologies enable building RestAPIs with ease. Techcello has followed this design principle in constructing the entire framework. All the functionalities are available as REST APIs for consumption.

However, I have come across few cases of project teams where design considerations are neglected. These considerations are mandatory to make the APIs truly RESTful. Let us look at some of them in this blog.

RestAPI versioning

If your Rest APIs are exposed for integration with multiple subsystems or with external systems, then it is mandatory that you version your APIs. You can achieve this using the following ways

Content Negotiation: Have versioning requested as a part of “Accept header” and version returned as a part of “Content” Header.
EXAMPLE,
http://company.com/api/customer/123
===>
GET /customer/123 HTTP/1.1
Accept: application/vnd.company.myapp.customer-v3+xml

<===
HTTP/1.1 200 OK
Content-Type: application/vnd.company.myapp-v3+xml

Neil Armstrong

Version as a part of URL: Have version as a part of the URI pattern
Example,

http://company.com/api/v3.0/customers/123

Both of these are adopted patterns in the industry. Let us look at what some of the popular RestAPIs use
Twitter – URI
Azure – Custom Header
Google Search – URI
Google Data API – URI or Header
As you can see, though Rest Purists advocate content negotiation many APIs do follow URI based versioning in practise.

Rest API Pagination

If the API needs to return lots of records it is better to include pagination. The best way to do this is to include link headers (Refer to RFC 5988).
Example, GitHub API
Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel=”next”, <https://api.github.com/user/repos?page=50&per_page=100>; rel=”last”
In addition to this the APIs can use custom headers to include pagination attributes such as

headers[“X-Pagination”] = {
total: results.total_entries,
total_pages: results.total_pages,
first_page: results.current_page == 1,
last_page: results.next_page.blank?,
….}

Related resources

Related resources of a resource should be linked. But sometimes it makes sense to expand it based on the client request.

Example,
GET /v1/accounts/ZugcG3JHQFOTKGEXAMPLE?expand=directory
Response
{
“href”: “https://api.mydomain.com/v1/accounts/ZugcG3JHQFOTKGEXAMPLE”,
“username”: “lonestarr”,
“email”: “[email protected]”,
“fullName”: “Lonestarr Schwartz”,
“givenName”: “Lonestarr”,
“middleName”: “”,
“surname”: “Schwartz”,
“status”: “ENABLED”,
“emailVerificationToken”: null
“directory”: {
“href”: “https://api.mydomain.com/v1/directories/S2HZc7gXTumVYEXAMPLE”,
“name”: “Spaceballs”,
“description”: “”,
“status”: “ENABLED”,
“accounts”: {
“href”:”https://api.mydomain.com/v1/directories/S2HZc7gXTumVYEXAMPLE/accounts”
},
“groups”: {
“href”:”https://api.mydomain.com/v1/directories/S2HZc7gXTumVYEXAMPLE/groups”
},
“tenant”:{
“href”:”https://api.mydomain.com/v1/tenants/wGbGaSNuTUix9EXAMPLE”
}

}
In the above example, directory alone is expanded based on the parameter and the other attributes – groups, tenants are linked.

These are few of the best practices for building an effective Rest API design. I will cover the rest in the coming blogs.