When you hear phrases like "that API is not RESTful" being thrown around, if you are like me, you end up questioning:
What really is REST, anyway?
How does something end up being RESTful?
So you do some research and this is the gist of what you end up with:
REST refers to Representational State Transfer . It is an architectural style for designing distributed systems using a set of constraints. The central abstraction in REST is a resource. The set of constraints defined by REST include:
A client-server model.
The Internet strikes again! You still have no idea what this means. All you want to do is make your API RESTful. I've been there. In order to understand what this means, let us first remind ourselves of the basic concepts of the world wide web.
What happens when you typehttps://scotch.io in the address bar of your browser?
The short answer is your browser (acting as a client), using HTTP, sends out a GET request to some server (in this case Scotch servers residing on Digital Ocean). The Scotch servers respond and your browser receives the response, which is in turn rendered into what you see.
In the client-server model, servers are the providers of a service or resource, with clients acting as the requesters of the resources. Clients can come in a wide variety of forms: as android applications, a browser running on a PC or an ATM machine.
The advantage of having the client-server style as a constraint is that it supports separation of concerns. As long as you have a separate machine (a server) providing the data, the clients can take any form, and may change independently.
In RESTful design, the server should not store any communication state. Sessions should be stored entirely by the client. This means that if the server receives two separate requests from the same client, it should not remember anything about the first request, by the time the second one comes through. Due to this, every request coming from the client should carry all the information necessary for an action to be performed by the server.
The rationale for this is that as the number of clients grows, the server will not have to keep track of all the clients it is talking to which would take a lot of time and space. This ensures that our overall system scales well.
This constraint basically says that your RESTful API should not have a login and logout function, which would involve the use of sessions, and isn't allowed. In order to authenticate and authorize clients, the server will look for authentication information within each request. Hence the client is in charge of storing authentication credentials, and sending them in each subsequent request. One such example is the use of JSON web tokens for authentication, and more information on this can be foundhere.
What is a Resource then?
A resource is a representation of either a virtual object such as an image, a real life thing such as a customer or a collection of objects such as a crowd. In essence, a resource can be anything. It is up to the API designer to decide which parts of his system should be mapped to resources.
Let's say you were providing a RESTful web API for a system running a chain of music stores which only sell banjos. Possible candidates for resources include banjos, stores, customers, employees, sales, users, visits and so on. The entities in the store (people and objects) and events (such as tour bookings) can all be mapped to resources.
In REST, every single resource should be unique. As such, it is only logical to assign IDs to our resources. For our chain of music stores, /store/1 and /store/2 would be two unique resources, with IDs 1 and 2. In practice, resources may also be nested. For instance, there may be an employee 2 in store 1, whose URI is /store/1/employee/2 .
The GET we mentioned is not the only HTTP verb. The common ones are POST , PUT , PATCH and DELETE . A major part of having a uniform interface in our RESTful APIs is using HTTP to provide CRUD (create, read, update and delete) actions for our resources. This table illustrates how a certain operation would intuitively map to an SQL operation and a HTTP verb.