Anand Chitipothu

Designing RESTful APIs

03 May 2018 – Visakhapatnam

APIs are all around. Everyone talks about RESTful APIs, but what does “RESTful” really mean?

Let us try to understand that using a simple example. Let us build an Address Book API.

Address Book API - the naive version

What are all the actions that you may want to do with an address book API?

  • list all entries in the address book
  • add a new entry
  • update an entry
  • delete an entry
  • search for an entry

For simplicity, lets assume each contact in the address book has only name and phone number.

The naive way to design the API is to come up with one url for every action that you want to have. So, you end up having the following endpoints.


We also need to worry about the request and response formats for each of those end points.

To delete or update an entry, we need to specify which entry to update. How do we identify an entry? Let us assume that each entry has a unique id.

So, the endpoint need to take the id, name and phone number as inputs.


And that responds back with:

{"status": "updated"}

What if we give an invalid phone number? It should fail with an error, right?

{"status": "failed", "error": "Invalid phone number"}	

This approach may look alright, but let us see how to design the same API in a RESTful way and compare both at the end.

Address Book API - the RESTful version

To design a restful API, we don’t start looking at actions, but at resources. Resources are just the topics/objects that you are dealing in the system.

Here we just have two types of resources, address-book and contact. Since we are always working with the address-book and there is only one, we can ignore that for now.

So we only have one resource type, “contact”. What REST suggests is to model the URLs around the resources. So you just have two URL endpoints. One endpoint for representing all contacts and another for each individual contact.


You might be wondering how to handle all those actions listed earlier. The RESTful way to handle that is to use HTTP methods for actions.

GET /contacts - list all the contacts
POST /contacts - create a new contact
PUT /contacts/$id - update a contact
DELETE /contacts/$id - delete a contact

What about search? You don’t really need a new one for search, just list the contacts but ask it to filter the results.

GET /contacts?name=foo - list all the matching contacts

Not only that, these HTTP methods have very clear semantics.

GET is always safe, which means GET request is not supposed have any side-effect.

PUT and DELETE are idempotent, which means making multiple identical requests will have the same side-effect of making a single request.

So, when designing RESTful APIs:

  • GET is used for reading any resource
  • PUT is used to replace a resource (both create and update)
  • DELETE is used to delete a resource
  • POST is used to create a resource and often overloaded for other actions

Now let us look at error handling. HTTP already has status codes. RESTful APIs try to reuse the same instead of reinventing a new way to deal with errors.

200 OK - all is well
201 Created - The resource you asked the server to create has been created
400 Bad Request - the server could not understand the request from the client
404 Not Found - The resource is not found
500 Internal Server Error - something totally went wrong with the server, not your fault

What to support both JSON and XML data types. HTTP is there to help you again. RESTful APIs use the value of request header Accept to decide which format to use in the response. Pass application/json as value of Accept header to receive response as JSON and pass text/xml for xml.

In short, “RESTful” just means using HTTP effectively!

If this sounds interesting to you and curious to learn more about RESTful APIs, please checkout my upcoming workshop Designing RESTful APIs on May 6, 2018.
blog comments powered by Disqus
Fork me on GitHub