Designing the best REST API

Note: This chapter assumes that you know what RESTful API is and will just focus on actual part of designing it. You can read about REST in wiki though, if you need some context to catch up.

The first thing you need to know about REST API is, it comes with different level of maturity. Means there is no over-arching standard for REST for everyone to comply with. In fact, many people and organization designs REST API differently. Generally, the higher the level of maturity of a certain REST API, its more scalable, extensible and easier to work with.

According to Leonard Richardson (an expert on RESTful API design, the developer of the popular Python library "Beautiful Soup"). There are 3 different Maturity Levels that you can employ:

Level 0

In your controllers, do you have methods like

• http://domain.com/processallaccounts
• http://domain.com/get_data_from_biller
• http://domain.com/create_new_account
• http://domain.com/customer_list_postback.php

Then you are POSTing and GETting some sort of data like JSON, XML etc via cURL or any sort of codes from your web/desktop applications?

If yes, or you are using any of these kind of thought process in your API, yes you are level 0 (equivalent of cave men) in terms of being technologically-advanced in REST API designs.

Level 1
Are you using the concept of "Resource" in your API? If you are familiar with "Entities", its similar to that. Its basically divides your api into "objects" that an api user can manipulate, instead of "methods" that a user can invoke. For example, lets say you have an API that aims to transfer a fund to another account:

In level 0, this is how it will look like
http://domain.com/process_account.php?sender_accountid=123&receiver_account_id=456&amount=5

In Level 1 API, this is how it will look like

Sender
http://domain.com/account/123?deduct_amount=5

Receiver
http://domain.com/account/456?add_amount=5

As you can see, in able to manipulate an "account", that object is uniquely represented by a url for that "resource", which is
http://domain.com/account/
everything that you want to do with that resource needs to happen in that url.
Ideally, for each object in your application that can be manipulated through api, has its own unique resource url to interact into.

Level 2
Are you using HTTP Verbs to determine the operation that needs to be carried out in your api? like

• GET - to fetch data
• POST - to create new data
• PUT - to create new data or update an existing data
• DELETE - to delete an existing data

Then you are Level 0, since you leverages the HTTP Verbs in your API, thus creating a context that is natively known by HTTP protocol itself. Like for example instead of building this kind of API:

Delete an acccount, you have this url  in level 0
http://domain.com/account/?id=123&operation=delete

In level 2, that should be like:

http://domain.com/account/123

Then, to indicate the operation, you will be using

DELETE /account/123 HTTP/1.1

 

Level 3

This level is a little hard to explain (this is the highest level of API maturity!), but let me get things started by summing up what we've got so far, so first, you have your resources, a unique url to manipulate every object in your API, then you are using HTTP Verbs to indicate what you want to do with those objects.

But let me ask you, what if you have hundreds of objects to manipulate? or each object, there are thousands of things that you do to it? To better understand this, lets get into a situation that you are very familiar with -- internet surfing.

When you are visiting any website, you don't know in advance the exact links that will presented to you right? like if someone give you a URL, like www.example.com, you have no idea what things to be found there, like where is the menu, how can I search, where is the contact form etc. Those things are being figured out "on the spot".

Means, websites allows us to "discover" things ourselves w/o any prior knowledge of what things can be found in their website. You figure out where is the menu, or sidebar or search bar on the spot, when you hit the website itself.

That very same concept is what Level 3 is about. This has actually some have catchy acronym -- HATEOAS (Hypertext As The Engine Of Application State). At the basic level, it allows the API end-user to discover things by themselves:

• What are the resources on this API?
• What do to with each of these resources?

Like for example, you have this resource

http://domain.com/account/123

without HATOEAS, this will probably just give you some sort of JSON response like

But with HATOEAS

I purposedly added several things in here to point out some concept. But one thing noticeble in here is, the contents of the JSON response using HATEOAS is kinda like how its been like if you are browsing a web page -- there are links in the menu to view the transactions of the account, there are links to the location etc. Basically, everything that you need to know "what to do next" is contained in that very same JSON response. Thus, the previous data "drives" you on how you will interact with the data.

In the next post, we'll continue with Collections and best practices in designing a REST api.

---

• ← Previous Post
• Next Post →