Top API Design Tips

Building a great API is a challenge. Designing your API in a way that is both useful and easy to use is perhaps the most significant challenge that many developers struggle to overcome. As your API becomes more popular it is imperative to continue to build upon it and so it has to be easy to improve. In this article we will look at some top tips for better API development.

Best Practices for REST API Documentation

Versioning is Imperative

We can’t stress just how important versioning is to any successful API development project. Even if this is your first time and you don’t know if there will be a second version it is still important. Also if it is just an API example. After all there is no cost associated with versioning but if you do succeed it makes letting everyone know that a better version is out much easier.

The fact is that changing an already published and well used API interface is a disaster. Most of your consumers already rely on that interface. There could be imperative business logic that’s associated with that API and if you change the endpoints that may fail. The consequences can be dire for some businesses and it would shake the confidence of everyone using the API.

Ideally, you’ll want to set the version in a way so that it is part of the URL since is the most transparent to users.

Using JSON

Most of us remember the time when we had to pass POST data as a URL. Though that is no longer the case. Also don’t use XML since that was outdated back in the 90s and you wouldn’t want to use SOAP either. JSON is a lot better and use it where you can to send data to all endpoints. It makes the requests readable and easy to assemble by the consumer.

Rails simplifies the process of handling parameters which are JSON encoded. You can use Rails’ ActionController to unwrap the data automatically which makes them accessible via params hash.

Handling API Errors

It may sound easy but handling errors in your AP requires a bit of planning ahead. Error messages should always be returned in the same format so that users don’t have to juggle different semantics from different resources. Plus, some languages may not support the use of arbitrary nesting in an JSON response and so will have trouble parsing it.

You may want to use an HTTP status code in addition to your error message handling. You can make things even easier for the user by including a link to an article or part of the documentation which explains the error. After all nothing is worse than an error message that’s hard to figure out.

If you want to go the extra mile, you can include a link to a matching article from your documentation when an error occurs so that the user can debug the problem immediately. Nothing is worse than an error with no or even a wrong error message. Always try to be as helpful to your consumers as possible!

Authentication Features

If the API is not intended for public use it needs some sort of authentication. In the past Devise used a TokenAuthenticatable strategy but that was removed. Though why should you need to use a complicated new system when HTTP provides a good enough authentication system with good basic authentication?

A username and password authentication can be handled by anyone. Basic HTTP authentication is used by almost every HTTP client so it works without any special additions.

Flip on to the server side and you get great support from Rails with all basic authentication in place which makes implementing them into API controllers easy. Additionally, while these authentication methods are good you should also have a way for users to sign in using their private tokens.

The tokens can be in the CI-server or any similar use cases. This type of system is always recommended when you are handing over access to all private resources to an external system to control access and don’t want to publish the password.


Good API design translates to better implementation and acceptance. So, the harder you work on developing something that is useful and easy to use the better will be its response.

About Harshit Jain

Harshit Jain is a tech-savvy blogger. He is graduated from Mumbai University. He likes to share his knowledge through his own blog at TripoSoft, Best Beard Trimmer, Best Electric Toothbrush & TechHug as well as by writing guest articles on other blogging sites. Follow him on Facebook, Google+, Twitter.

Leave a Reply

Your email address will not be published. Required fields are marked *

CommentLuv badge

This site uses Akismet to reduce spam. Learn how your comment data is processed.