RESTful Services – Best Practices on Consuming APIs

Introduction

REST is everywhere, almost everyone. Most of the popular services in the Web 2.0 world are REST-based (REST is an acronym for Representational State Transfer, an architectural style published by W3C Technical advisory group) as the popularity of SOAP-based services has waned down.

Apps that interact with RESTful services will benefit from following a few best practices.

Read the API and Its Documentation

It goes without saying that to consume the API correctly, the caller should understand the language of the API. With REST, we have actors and actions. Developers should familiarize themselves with the layout of the APIs that the service exposes to make sure they are calling it for the right purposes. API documentation can help. If you are a developer who exposes the REST API, look at the Facebook API documentation to get an idea of what good documentation looks like.

Use JSON Over XML

If the REST API offers payload support for both JSON and XML formats, use JSON. It is simpler and has parser support for more languages. XML is harder to parse and its parsers can hit bugs. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.

Use SSL if Available

If the REST API offers SSL support, do not cringe at the opportunity to use it. Instead, use it like you have no other choice. Why? Because you have no idea how and where your application is going to be called from. SSL also prevents the need to implement a simple access token; that can avoid a lot of hassle if a part of your application needs to make calls that require security. The overhead on processing is often less than 20%.

API Idempotence

Not all APIs are idempotent. As an API user, be aware of this behavior. If the API result varies by call, consider using another API (if available) to get the information you need.

Updates

The beauty of REST lies in the fact that the output payload of GET (read) call is very similar to the input payload PUT (update) call. To avoid conflicts during updates, it is recommended to get the state of the resource, modify the response and then update it via a PUT call.

For example:

1. Make the fetch call first.

   Request: GET //VIP/Person/23.

   Response payload:

   {
      "firstName": "John",
      "lastName": "Smith",
      "isAlive": true,
      "age": 25,
      "height_cm": 167.6,
      "address": {
         "streetAddress": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postalCode": "10021-3100"
      }
   }
   

2. Make changes to the output as needed.

   {
      "firstName": "John",
      "lastName": "Smith",
      "isAlive": true,
      "age": 26,
      "height_cm": 167.6,
      "address": {
         "streetAddress": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postalCode": "10021-3100"
      }
   

3. Now update the server with the information.

   Request: PUT //VIP/Person/23.

   Request payload:

   {
      "firstName": "John",
      "lastName": "Smith",
      "isAlive": true,
      "age": 26,
      "height_cm": 167.6,
      "address": {
         "streetAddress": "21 2nd Street",
         "city": "New York",
         "state": "NY",
         "postalCode": "10021-3100"
      }
   }
   

   This way of updating ensures your update does not remove other information associated with the resource.

Concurrency Conflicts

When two updates are made to the same resource at the same time, the default behavior is that the last update wins and its changes are persisted. Smart programming practices dictate that you use conditional updates using the eTag feature. When making a GET call (as described earlier), look for the eTag signature that the API returns, and when you make the update, make a reference to that eTag. This is equivalent to saying, make an update if the timestamp on the server hasn’t changed from the last call. If the timestamp has changed, the conditional update call will fail, preventing you from accidentally overwriting someone else’s changes.

Summary

I hope the above tips will help you write high quality apps that consume REST APIs.

About the Author

Vipul Patel is a technology geek based in Seattle. He can be reached at vipul.patel@hotmail.com. You can visit his LinkedIn profile at https://www.linkedin.com/pub/vipul-patel/6/675/508.