RESTful APIs Part 4

So far we have discussed why we needed something better than we had and how REST relates to features of the HTTP protocol. Now we will actually talk about what REST means and how it will help us.

REST - What is it?

In part 2 we mentioned that REST stood for representational state transfer. It is an architecture used to create APIs and as a general rule is the architecture that is coming to dominate APIs on the internet. There are a few architectural requirements for REST that are particularly important. One thing to keep in mind is that there are different levels of adherence to the REST requirements and so if you are trying to access someone else's implementation they may not fully implement each of these.

There is a Separation of Servers and Clients

In a RESTful API your servers and clients will always behave differently. This isn't a new concept or in any way exclusive of REST. However, it is good to recognize the distinction between a server and a client.

Thinking back to how REST uses built-in features of HTTP it makes sense that they are different. In particular, you will recall that the client sends a HTTP Method such as a GET or a POST as part of the information and which describes what the server should do with the data. The server then sends a status code letting the client know what happened with the request.

Additionally the client establishes a connection to the server with a request and the server can only respond through the connection. The server can not arbitrarily decide to connect to any of its clients. In fact once the response to the client is sent the server no longer has any way of knowing if the client still exists.

If you need to have a way for the server to push changes to the client there are other protocols and architectures you can use but not REST.

It is Stateless

REST is also stateless. This means that server does not store the state of the client. This feature helps with scaling as you can have more than one server handling requests and we don't care which server we access with our request since we will always get the same response because none of the servers have any special information on how to deal with that client.

Often APIs will require some state. Specifically is the user logged in or not and if they are logged in do they have access to the end-point they want to access. In this case what is done is the client has to send its state with every request.

However, we can't trust the client to tell the truth. Picture a man walking up to a nuclear silo and say, "I have clearance to access and launch nuclear missiles" and then the guards taking his word for it. It isn't going to happen! Generally what happens is the server will give the client a token which they will include whenever they communicate with the server and then the server will access a database which will say if the token is valid and what it allows the client to do.

It has a Uniform Interface

This is the one area where there is often a lot of variance between the architecturally idealized design and the real implementation. In its basic sense the uniform interface means that there is an interface that is always the same regardless of what component you are accessing.

This can have some limitations so they have some constraints on how you should implement it, which is viewed as a bit over the top for most APIs as they are generally fairly simple and/or the components have similar information.

Here is a list of the constraints:

  • identification of resources -- you can specify the format you want, JSON, XML, etc..

  • manipulation of resources through representations -- you can modify a resource through any of the representations returned

  • self-descriptive messages -- the representation tells you how to process the message

  • hypermedia as the engine of application state(HATEOAS) -- the representation/message includes the links you can use to perform an action

As a general rule the external RESTful APIs have basically ignored the identification of resources and HATEOAS. I have seen a couple that let you specify JSON or XML but normally that was the limit of your options. I have never been able to use an external API which implements HATEOAS but it is pretty neat since it removes many of the problems that require versioning of the API. It makes it so you only need the initial link into the base system then it gives you all the other links you may need so minor changes don't matter.

Other Stuff

REST does have a few other features that are less critical that we go in depth into for a general overview. These include things like reporting the cachability of the resource, allowing for the concept that the communication can travel through many layers, and that RESTful APIs can return code which the client can execute.

Learning More

In the next article I will bring it back home and give some more detailed examples of how RESTful APIs actually work.

In the mean time if you want to learn more about REST a good place to start is with the actual paper that Fielding wrote defining REST. Here is a link to Fielding's paper.

comments powered by Disqus