RESTful API Design

So what exactly is the REST Architecture Style? The genesis of REST can be found in Roy Fielding's thesis. You can find millions of articles out there which you can read at leisure. Each has it's own terminology and there are lot of philosophical discussions about what REST is and what it isn't. I respect all that, but we will avoid the idealistic debates. We will rather focus on how many software companies have amalgamated (polluted or evolved, that discussion requested to be avoided here!) HTTP and REST principles for their API Design. This amalgamation and practical industry usage is simply what I will address as "RESTful API Design". Keeping in mind this, we will use the following terminology through this blog in the practical example we are taking - the EchoSign REST API

RESTful API Design involves breaking the system in terms of resources, and providing access to those resources through endpoints (also called operations) defined on the web service's base uris. Access is  done using standard HTTP Methods and controlled by an auth mechanism. Configuration for the resource is provided and obtained through request and response with HTTP status codes communicating the status. Lets get a 20,000 feet overview of each of the buzzwords. Deeper dive in future posts

1. Resources are the entities that exist in the system being made RESTful. For instance, in case of a blogging website, these can be the blogs, posts and comments.For an online shopping portal, the resources are customers, products and orders. In case of a EchoSign, they are agreements and users (pic on your left)

2. EndPoints or operations provide a mechanism through which these resources can be accessed. For instance, the endpoint to list all the blog posts on a particular blog would be a GET on /blogs/{blogId}/posts. To create a new order in the shopping portal, one would do a POST on /orders endpoint. The details of a specific agreement in EchoSign can be obtained by doing a GET request on /agreements/{agreementId} endpoint

3. Base URIs  define the web uri location where the resources are available through the endpoints. To take a real example, for Google blogger the base_uri is https://www.googleapis.com/blogger/v3. For the EchoSign e-signature solution, the base_uri is https://api.echosign.com/api/rest/v3. To perform operations on resources, simply append the endpoint to the base_uri. In EchoSign, use a GET on https://api.echosign.com/api/rest/v3/agreements/{agreementId} with agreementId as the identifier  to get the complete details of that agreement (pic above)

4.  HTTP Methods is where the simplicity of REST lies. In RESTful API design, operations on resources are  done through the standard HTTP methods, primarily GET, POST, PUT and DELETE . Other HTTP methods - OPTIONS, HEAD, PATCH are also used in some cases. Following are some of the methods and end-points available on the EchoSign agreements resource

5. Auth collectively represents both authentication (identifying yourself to the system) and authorization (level of access based on your identity). There are multiple auth mechanisms that REST APIs use. EchoSign, for instance, currently supports API_KEYS, BasicAuth access token and OAuth based access tokens. The EchoSign REST API documentation allows you to single click and interactively issue OAuth access tokens of the desired scope for different end-points. For instance, below we are requesting for an OAuth access token which allows an admin to view details of a user in her account. 

6. Request and Response  are same as in standard client-server communication. Request, provides a way to specify details for creating/updating a resource or filters for getting to a specific resource. Response in turn returns the specific resource id or it's details. Most systems use JSON format for the request body and response though one can also use XML. 

7. HTTP Status codes are returned with the response to convey back the status of your request. Some common ones are : 200 - Success, 201 - Created, 400 - Bad Request, 401 - Unauthorized,  404 - Not Found and 500 - Internal Server Error

In the pic below, you can see the request and response for getting the details of a specific user in an account along with the status code which is 200 - Success in this case

And that my friends is a bird's eye-view of RESTful API design. Many of these points deserve a POST of their own and they definitely will GET one. Stay PUT!

The API Biography continues - Take 3 - Web Services

Come mid 1990's it was time to get out of the box. Yes, literally! Till before this time, APIs were mostly about desktop applications calling into the Operating system or desktop applications calling into each other. But at this time, that is the Networking Era, the embedded industry, intranets and internet were starting to gain much visible presence. Hardware and software vendors wanted to communicate between applications outside / across the box - be it those running on desktops, or an chip in an embedded system. The problem was now even more interesting since these applications could be on completely different operating systems, written using completely different technologies and located in completely different locations. A common language or protocol was needed to communicate between these varied application and that resulted in the birth of Web Service APIs. 

The first in line was the SOAP protocol that was created by some top IT companies of that time like Microsoft and IBM. It began as the mechanics to do a Remote Procedure Call (RPC) over HTTP using XML but soon gained traction and became a W3C recommendation. Every big and small company that created web-apps started exposing their services or facilities through APIs so that other desktop and web-apps could integrate with their service. This was quite similar to the desktop app plugin model, but with no boundaries on consumptions. The desktop app plugins were limited to specific operating systems for consumption and after the user had installed the app and the plugin. In the web world, the web services APIs could be consumed from anywhere with zero install requirement. For instance, one could make a SOAP Web service call to get the weather of a city from a weather service, have a document converted to a PDF through a document conversion service or get the latest stock price from a financial web service.

In parallel to all this, the World Wide Web (www part of the Internet) was really picking up speed every day - proliferating faster than Agent Smith in the Matrix as it continues today. Notice in the pic above what all has happened in the minute you were reading this. The www was governed by the HTTP protocol and a growing collection of pages, resources and URLs. In 2000, one of the proponents of HTTP, Roy Fielding, presented his thesis that totally changed the face of Web Service APIs. Though SOAP had been growing aggressively, it had it's own problems of being procedural, heavy and complex to construct. Fielding proposed REST, an architectural style based on the standard www principles. With it's clean design around resources, URLs and CRUD operations (Create, Retrieve, Update and Delete), it looked so simple and obvious that it immediately got all the heat.  What was a thesis chapter back then, has now come to define how most modern web services like Facebook, Dropbox, Google and Adobe expose their functionality to their integrators. 

We will cover all this and more about REST Web Services and RESTful Design  through this blog.