Building Effective REST APIs

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.

Print Friendly

Janaki Jayachandran

Janaki serves as the Director of Technology at Techcello. Janaki has more than 15+ years of software development experience. He is responsible for product engineering, support and evangelization of Techcello. Prior to Techcello, Janaki worked with Aspire Systems as Delivery Manager and Practice Manager focused on Microsoft Technologies and SaaS/On-Demand product development. He has worked with several ISVs and enterprises in building multi-tenant, cloud enabled products. He has travelled widely across the US and UK for working with various customers. Janaki is an ardent cloud enthusiast and a prolific speaker at various cloud conferences including Interop, SaaS University, Cloud Connect and Euro Cloud.

More Posts - Website