Practising REST 1

That, an API is not SOAP does not mean that it is RESTful. Usually, we talk of whether an API is going to be REST or SOAP and, as such, once we are not using xml and Stubs, we say we are using REST. When we talk of REST in that limited sense, it’s value to us is the fact that it is very simple to work/integrate with (Or is it?). Typically, you create a Servlet or Controller method that receives a request at some URL and returns some JSON response. Anyone  who needs that functionality can make a call to that URL, exercising whatever functionality is exposed there and getting the response.

So, for instance, you manage a users domain. You want an API client to be able to retrieve a user’s details by email so you create a method getUserByEmail(String email) on the URL path “/user/getByEmail?email=" that returns a JSON with the user’s details. You also want an API client to be able to make a user an administrator so you create an api method makeUserAdmin(String email) that takes a user’s email and sets the user’s administrator status to true. This may be on the URL path “/user/makeAdmin?email=". Simple? Well, this is not REST.

I am not going to try to explain REST. There are many resources online including the original paper by Roy Fielding. I will only share some understanding of REST that is necessary for showing its relevance to a programmer who needs to build an API that will allow others use his application.

So, first thing, with REST you don’t expose procedures (methods) in your application for clients to call. That will simply be enabling clients to Call your Procedures Remotely (RPC) without the conventions of SOAP. With REST, you expose a Resource and allow retrieval and manipulation of the resource by a transfer of Representations of the resource through a Uniform set of methods. In the case of HTTP which is a protocol that follows the REST Architectural Style, this Uniform set of methods are GET, POST, PUT etc.

In the users example above, we could expose a users resource that will be available at the URL path /users. We could then implement a GET for that Resource which will return a Representation of the users in the system. The users resource can be thought of and modelled as a list of another resource user which represents a single user in the system. A GET on the users resource will then return a representation which is a list of a representation of every user in the system. The representation of a user may contain the user’s id, email, name and whether or not the user is an administrator. If we are using JSON, a GET on users may return something thus :

{
  {
    id:1,
    email:"dennis@yahoo.com",
    name:"Dennis",
    admin:false
  },
  {
    id:2,
    email:"sylvia@yahoo.com",
    name:"Sylvia",
    admin:false
  },
  ...
}

What if I didn’t want all users, just the user with email dennis@yahoo.com. That is really still a GET on the users resource except with the constraint that we are only interested in users who have the said email: /users?email=dennis@yahoo.com. What about if you wanted only users that were just administrators? I don’t need to tell you. This point of me not needing to tell you requires further discussion which we shall have later.

Like I mentioned earlier, in addition to the users resource for users in the system, we can have a user resource for a single user of the system. That can be on the url path users/{userId}. To GET the first user, you perform a GET request to /users/1. What if I wanted to change the administrator status of this user? I create a representation of the user as I want it to be which is:

{
  id:1,
  email:"dennis@yahoo.com",
  name:"Dennis",
  admin:true 
}

Then I can POST or PUT this new representation to change the state of the user in the application. This corresponds to an HTTP POST or PUT to the path /users/1 with a Request Body that contains the JSON specified above. What if I wanted to change the name of the user to Asamoah? Yes, again, I don’t need to tell you.

The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. By applying the software engineering principle of generality to the component interface the overall system architecture is simplified and the visibility of interactions is improved. – Roy Fielding

So you see why you should build a RESTful API. By simply accessing /users, I could know how to do so much on your system. As a matter of fact, a much more RESTful response from the GET on the users resource will be more like this:

{
  {
    id:1,
    href:"/users/1",  //the addition
    email:"dennis@yahoo.com",
    name:"Dennis",
    admin:false
  },
  {
    id:2,
    href:"/users/2", //the addition
    email:"sylvia@yahoo.com",
    name:"Sylvia",
    admin:false
  },
  ...
}

By accessing the users resource, I know how to get users based on email, name, and administrator status. I know the path to get a particular user. Once I get the user, I know how to change any of the user’s details. In fact, I know how to create a new user. I simply make a POST to the users resource of a representation of a user that does not already exist.

This is very much how you navigate the web, identifying and utilizing various resources. When you visit a website, no one gives you a documentation of all the paths that are available and what you can get from the website. Instead, once you get the first page, you see hyperlinks that tell you what is available and on and on you go till you have used everything usable on the website.

Likewise, when you build a RESTful API, your consumers can very much discover the functionality available rather easily. Also, the architecture is so simple that is easy to think about what you’ve done. And, simplicity is very valuable. There are no hidden interactions or, at least, they are minimized. You can tell the impact that each exposed link has on the Application State. What Resource is being manipulated and with which Representation? This is good for security, for instance. You can easily look at your Resources, what HTTP methods you allow on those resources and what authentication is necessary for each resource.

Since, I recently told one of my colleagues that his blogs are very verbose, I will end here lest I’m accused of same. I will certainly follow up with another post on practising REST.

Advertisement

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s