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.
| Resource | POST | GET | PUT | DELETE |
|---|---|---|---|---|
| /dog | Create a new dog | List dogs | Replace dogs with new dogs(Bulk update) | Delete all dogs |
| /dog/1234 | Error | Show dog | If exist update dog else ERROR | Delete dog |
I know there is confusion surrounding PUT and DELETE. Read more about RESTful PUT and DELETE functions, and here for clarifications on why use PUT DELETE POST GET from helpful Stack Overflow posts.
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:
{
"status": 401,
"error_code": 2005,
"error_message": "Authentication token has expired",
"more_info": "https://dasunhegoda.com/api/doc/token_error"
}
You can make use of HTTP status code for this purpose.
4. API Versioning
In any API, versioning is important to maintain consistency. It can be done in many ways but below are my preferred methods:
Method 1
You can use the letter ‘v’ in the URL to denote the API version as below.
https://dasunhegoda.com/i-passed-40k-on-stackoverflow-com/1384/
Method 2
You can use the additional parameter at the end of the URL.
https://dasunhegoda.com/i-passed-40k-on-stackoverflow-com/1384/
There are various opinions on using API versioning. This Stack Overflow post on best practices for API Versioning is useful.
5. Filtering
Don’t provide unnecessary data to your API consumers. It will clutter your REST API unnecessarily. Instead, let the developer choose what he needs.
For this we can use filtering methods in our APIs:
/dogs/1234?value1,value2,value3,value4
You can also use pagination for this purpose where you don’t have to return all the results at once. The query below is similar to MySQL:
/dogs?limit=25&offset=20
You can read more on how to design RESTful search filtering in this helpful Stack Overflow post.
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.
9. Stability and Consistency
Depending on your requirements you should consider a highly available architecture for your REST API. If you are wondering how to implement high availability in your REST API you can read my article on high availability deployment architecture.
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.
