Best practices in using RESTful services

RESTful services are stateless, client-server based, cacheable and leverage resources. These resources have a common interface and are uniquely addressable using URIs. In this post, I’ll present some of the best practices that can be followed when building RESTful services.

REST and resources

The REST architectural paradigm is based on the concept of resources. These resources are used to represent state and functionality and are identified using URIs. Note that in a REST-based architecture, the clients and servers communicate through requests and responses — the client sends a request to the server for a resource if need be and the server locates the resources and sends it back to the client as a response. A request in a REST-based model comprises of the following:

1. Endpoint URL — this denotes the address of the resource
2. Developer ID — this is a key that is used to identify the origin of a request
3. Parameters — you can pass parameters to a request much the same way you do with any other method calls
4. Desired Action — this implies the action that needs to be performed for the request

Now that we know the basics, let’s have a quick tour of the best practices we should follow when building RESTful services.

Error handling

When building RESTful services you should handle errors using HTTP status codes. This doesn’t mean that you would return HTTP 500 with a stack trace each time an error occurs. Rather, you should send out meaningful error codes that correspond to the error that has occurred in the method of your RESTful service. You can take a look at this link to know the HTTP status codes and their purpose.

Format the error appropriately — make sure the format is compliant with the way you would need to consume it so that you can display the error in the user interface. You should also map the exceptions in an error payload so that the user interface can display a meaningful error to the end user.

Versioning

When designing your API you should keep in mind that your API might have to be changed over time to make it stable. You should always version your API – you shouldn’t release an API that isn’t versioned. To version your API you can use a simple ordinal number and avoid decimal notations like 1.2 or 1.5, etc. The following URL shows how a versioned API looks like:

/idg/authors/blog/api 

RESTful URLs and actions

You should use nouns in the URL and not verbs. Let’s take an example. Refer to the URL given next.

idg/api/getauthors

Now suppose you want to use the same URL with a different HTTP verb. It becomes confusing, correct? What if you need to make a HTTP POST request to the same API? The purpose becomes self-defeating. You should note that no matter what HTTP verb you use, the URL should never change. So, the modified URL should be something similar to what is given below.

idg/api/authors

You can use this with any HTTP verb of your choice — you needn’t change the URL anyway.

Follow the RESTful principles – separate your API into logical resources that can be mapped to the HTTP verbs (GET, POST, PUT, PATCH, and DELETE). The following is an example.

GET/authors – retrieves a list of authors

Your REST URL should be simple — follow the Keep it Simple, Stupid (KISS) principle.

Security

It is always advisable to use SSL for your API when it is in production. HMAC authentication to secure your API. Incidentally, HMAC authentication uses a secret key for data exchange between the server and the client. There are many other ways to secure your API — you can refer to MSDN for more information. You can know more on how HMAC authentication can be used to secure your Web API from this link.

Reduce the payload

Always keep the resource URLs clean and lean. You should limit the data returned from your RESTful service method by using appropriate request filtering. You should use JSON in lieu of XML to exchange data in your API as XML is verbose, difficult to parse and consumes more payload. You can also use sorting to sort data in ascending or descending order.

You should use paging to limit the data returned and hence reduce the payload. Paging should be used when you are dealing with large amount of data.

Documentation

Your RESTful API should be properly documented. The documentation should specify the complete request and response cycles. You can take advantage of Swagger to document your API — there are many other tools though. Here’s the link to Swagger.