In the last post, we saw how every company is building an API for its services. Other companies can then access the services in their own apps. This builds an ecosystem around the company’s services and the company builds both its reputation and its business. But you will see that companies are now building ‘REST’ APIs. REST stands for REpresentational State Tranformation. It is a clunky, overly technical term that even those from technology fail to understand, let alone hope to build an API which is ‘REST-compliant’. In this post, I will completely dejargonise the term and explain to you what it means by taking a very common activity: Reading a book, inserting bookmarks and marking with a highlighter.

API for reading a book

You are reading a book. Now let us talk about how you will create an API around a book. As discussed in the last post, APIs are simply HTTP URLs used by an app to do something on a company’s service. The company publishes the list of URLs that can be used. The app can only choose from those URLs. If you are the book maker, you start by identifying the functionalities.

• Getting the details of a book, e.g. title, author, year of publication, publisher, etc.
• Turning to page X.
• Getting a list of all the bookmarks set inside a book.
• Bookmarking page Y.
• Removing bookmark from page Z.
• Marking line A of paragraph B on page C with a highlighter.

Corresponding to these functions, the you would create the following URLs. These are also called API endpoints.

• GET http://www.mybooks.org/get-book-details?book=power-of-habits
• GET http://www.mybooks.org/get-page?book=effective-executive&page=127
• GET http://www.mybooks.org/get-bookmarks?book=anasakti-yoga
• POST http://www.mybooks.org/set-bookmark?book=unleash-the-power-within&page=9
• POST http://www.mybooks.org/delete-bookmark?book=work-the-system&page=33
• POST http://www.mybooks.org/highlight-line?book=rich-dad-poor-dad&page=28&para=3&line=5

Now that you have created a set of API endpoints, you can publish them on your developer website with all the documentation. You will notice that all the URLs are prefixed with words like GET and POST. Without getting into the details, let’s say that GET is used to extract information from a service without modifying any data in the service, while POST is used to modify data in the service. Getting information about a book is simply extracting data from a book, whereas bookmarking and highlighting are actually making changes inside the book. Note that you have not released an APIs which would allow someone to rewrite the contents of the book itself. The only modifications they can make to a book are bookmarking and highlighting. APIs need to planned in such a way that you only allow the minimum necessary changes to your data, whereas as much information can be extracted for reading.

This is how APIs used to work and everyone was happy. But suddenly, everyone realised that too much work was going on. Too many URLs were being produced and each URL had this clunky looking question mark followed by a set of mathematic looking assignments with equals to sign. Also, the API maker had to document every API endpoint. There was no way for the API user to discover other API endpoints based on the one he/she is currently using. Let us see how too many URLs were being produced. Look at the API URLs 2 through 4. All of them deal with bookmarks. Yet there are three different URLs: get-bookmarks, set-bookmark, delete-bookmark. More streamlining was desired and developers put their heads together to see if only one URL would suffice. Secondly, the parameter list begins to look unwieldy with its ?a=b&c=d&e=f format. API endpoint 6 for marking with a highlighter needs 4 parameters and the URL looks really ugly. Was there a way to shorten the URL to something more elegant? If we were to use a proper standard system to form URLs, wouldn’t it be easier for URLs to be discovered by developers naturally instead of the API maker having to document each one?

REST APIs

To address the above problems, REST APIs were made. Here is how each of the above endpoints will look if produced as REST API endpoints.

• GET http://www.mybooks.org/books/power-of-habits
• GET http://www.mybooks.org/books/effective-executive/pages/127
• GET http://www.mybooks.org/books/anasakti-yoga/pages?bookmarked=true
• POST http://www.mybooks.org/books/unleash-the-power-within/pages/127/bookmark
• DELETE http://www.mybooks.org/books/work-the-system/pages/33/bookmark
• POST http://www.mybooks.org/books/rich-dad-poor-dad/pages/28/paras/3/lines/5/highlight

You can see that the URLs are now short and elegant. They represent a hierarchy of pages within books, paras within pages, lines within paras, bookmark for page, highlight for a line, etc. Also different verbs such as GET, POST and DELETE for the same URL are used to mention different operations. From URLs 2 and 3, you can see that any operations on pages is achieved with the end point ‘pages’. To fetch one page, you should specify the page number, whereas to specify a range of pages, which in our case is all the bookmarked pages, you must specify the condition after ?.

/pages/<page number>/bookmark is the pattern used whether you want to insert or delete a bookmark. POST is used to insert and DELETE is used to remove. The verbs GET, POST and DELETE are already known by developers using REST. So we only need to give them the end point URLs that make up the objects and the hierarchy between them. In our case, we only need to document that the URLs can be the follow the following hierarchies.

/books/<book ID>/pages/<page number>/bookmark
OR
/books/<book ID>/pages/<page number>/paras/<para number>/lines/<line number>/highlight

The developers will use various verbs like GET, POST and DELETE to discover what operations can be performed on the various objects along the hierarchies, i.e. books, pages, bookmarks, paras, lines and highlights.
There are also ways in REST for developers to be able to discover the hierarchy itself without the documentation, but that is beyond the scope of this blog post. One can use a concept called ‘linked data’ and HATEOAS to let a developer discover hierarchies of objects after we supply the documentation of just the main object to the developer. In our example, if we were to use linked data, we only need to tell the developer the URL for books, i.e. http://www.mybooks.org/books. Everything else inside such as pages and bookmarks will be discovered based on the linked data.

Conclusion

REST APIs can make APIs look more natural by using a path of hierarchy among objects. Functionalities can be discovered without having to explicitly document them. As more companies discover the simplicity and flexibility of REST APIs, we will see new REST APIs spring up and more traditional APIs being converted to REST APIs. What is your next step?