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!