REST best practices 101

Our latest edition of API Expertise features a special guest post on REST API Best Practice from Dasun Hegoda, Technical Lead at Information and Communication Technology Agency (ICTA), Sri Lanka. This blog was first published at www.dasunhegoda.com.

SOA (Service Oriented Architecture) has become a foundation for the most of the applications that are developed today. A service oriented architecture is an architectural pattern which enables a collection of services to communicate with external/internal parties to pass data or for coordinating services. Let’s start from the beginning…

What’s a Service/API?

A service is a function that is well-defined, self-contained, and does not depend on the context or state of other services.

In other words it’s an interface used by software components to communicate with each other. Let’s understand the difference between API and Web Services. A Web Service is a type of API, almost always one that operates over HTTP. In the modern world there are two types of web services that are used:

SOAP

REST

We can’t compare REST with SOAP since SOAP is a protocol and REST is an architectural pattern. People mostly get confused when selecting one for their application. If you are wondering what’s the difference between these two you can get a good start from this Stack Overflow article on SOAP vs REST.

Our focus today is on REST. How we can implement a perfect REST API? What are the best practices? Let’s get down to business.

1. Abstract vs Concrete

When designing a REST API you should endeavour to make the API as concrete as possible. It will make the API less confusing to your consumers.

2. CRUD Operations

There are four available methods when designing a REST API; GET, POST, PUT and DELETE. Below is a proposed methodology to implement CRUD operations in a REST API. Note that this is suggested by me and you can alter this as per your requirement.

3. Error Handling

Error handling gets less attention but is the most important part of any REST API. You must give as many hints as possible to your API consumer about the error and why it has occurred. Also, make sure that throughout the API you provide granular level error messages. Below is an example:

6. Security

Security is one of the major concerns when compared to SOAP because there are no standards such as ws-security defined for REST.

You can use HTTPS across your APIs.

Don’t forget to include a timestamp in each API request and response. Make sure to log them all. In case of a dispute, you can refer to them.

Use an access_token to make sure that API is invoked by the trusted parties. You can supply the access_token so only API consumers with the access_token can invoke the API. Read more.

7. Analytics

Once you start logging every API request and response you can build an analytical platform on top of that. If the number of records are high you might have to consider Big Data technologies. Having analytics in your REST API will give you a good insight of what’s happening your API.

8. Documentation

Proper Documentation is vital for the API. It doesn’t matter how great your API design is if your API consumers can’t use it properly. You can use tools such as apidocjs for this purpose. It’s really easy to get started with.

10. URL Structure

You have to structure your API URL in an intuitive manner. Select a domain which is easy for marking as well. Eg:- api.yourdomain.com. When structuring your REST API you can use the following format:

GET tasks/5/messages – Retrieves list of messages for task #5

GET tasks/5/messages/10 – Retrieves the 10th messages for task #5

POST tasks/5/messages – Create a new message for task #5

DELETE tasks/5/messages/10 – Delete the 10th messages of task #5

PUT tasks/5/messages/12 – Update the 12th messages of task #5

If you have developed your REST API properly you should have the above features in it. You should keep these in mind when designing your REST API.

So that’s it about REST API architecture. If you have any questions or would like to read more about some of my projects, visit www.dasunhegoda.com. Your feedback is highly appreciated.

Dasun Hegoda is a Technical Lead at the Information and Communication Technology Agency (ICTA), for the Government of Sri Lanka. He specialises in Enterprise Application Development (EAD) with more than 6 years of industry experience in the field of IT & Digital Arena.

Got some API Expertise you think the Tyk community would benefit from? We’d love to see it! Get in touch – the most relevant or insightful pieces will be considered for our blog.

Privacy Overview

This website uses cookies so that we can provide you with the best user experience possible. Cookie information is stored in your browser and performs functions such as recognising you when you return to our website and helping our team to understand which sections of the website you find most interesting and useful.

You can adjust all of your cookie settings by navigating the tabs on the left hand side.