REST API
When I was conducting a recruitment interview, I often met people who worked with Web APIs, but didn’t really know anything about it. Of course you can work with some technology, knowing only minimum that you have to know, but then you wouldn’t be here, right? Next couple posts will be about everything you should know about REST API.
What is REST API?
To answer this question we need to learn what Web API is. It’s very difficult to define Web API, because it’s fundamental concept. Web API is an interface which has a set of functions that allow others to access resource or feature, over HTTP. It can be used by everything that uses HTTP. So clients can make call manually thru web browser, our application can call for data to display it or even multiple web services can contact with each other.
Additionally our service will respond with data instead of view, so when we call for “student” resource, we will get plain text list of students instead rendered table with students in it. This is why, Web API is so universal. Server handles only backend stuff, to get response back to user in simplest form. Then client can do with it whatever he wants and by client I mean someone who will consume our API.
Now, REST API is, similarly to Web API, a collection of resources, which follows set of rules. Those rules were invented to help developers create easy to use and maintain APIs.
The most important Statelessness.
It means that our API doesn’t store any user context. Simply it doesn’t remember any user information or application state. Each request from any client contains all the information necessary for API to respond. It simplify work for clients, there aren’t places where client need to send some data and other which are stored. Client have to send everything, every time. If it’s not clear, here’s example.
We’re using online book reader. You want to start reading book from page 2, when you’ve finished reading this page you can’t just ask for next page. You need to send request for page number 3. This is true meaning of “Send all the information necessary for API to respond”, our API don’t remember what client was doing, so it need every piece of information to work.
It is very simple scenario, our state can by anything. For example we can assign user to file share when he run application first time, and from that point he would search files only from this one file share. While having session on Web API may be beneficial in some cases, in most having stateless service is better and in REST API it’s mandatory.
What does that give to us?
First of all, we can transfer some of responsibilities from our Web Service to client. State didn’t disappear, client is responsible for remembering his state.
We can scale up our Web API without problems, because any server can handle any request. It’s harder to do that with stateful services. Every stateful service would end up with its own state, so in no time there would be instances that could answer only to some of client, it can’t work.
To achieve the same we would need to create shared context between every instance of stateful service for example by storing session inside database, but then every time user sends request our API need to check session in database and then proceed to answer his request. It shouldn’t be a problem, but why making your work harder?
What about persistent store?
Storing data in database make our API stateful, or some may say that. But there are two types of state, application state which I described before and resource state.
Resource state is a state that needs to be persistent and survivable even after client stops working with API. For example when we update our database with new student. We want to be able to query every student from our Web API, even those recently created.
Having resource state won’t make usage of Web API any harder. REST was created to deal with abominations. I worked with API that had endpoint which locked user to one resource during first use, for example one set of documents and every action from that point have been taken within context of locked resource. I didn’t know it and was wondering why none of my action do anything to the rest of documents. Stateless service is clear, we can predict what it will do.
Outro
To sum up, statelessness simplifies usage of REST API making it less complex. It let us scale up the APIs, because every instance can handle any user request. Finally it help us, developers, because we don’t need to worry about application state, it’s client’s job.
That’s all for this week, next time, we will learn about next rule of REST uniform interface. I’ll show you how REST Endpoint should looks like and what should it return. So if you’re interested come here next week. As always, if you have any question feel free to ask them, I’ll make sure that you will have your answer.