REST stands for ‘Representational State Transfer’ and it is an architectural pattern for creating an API that uses HTTP as its underlying communication method. REST was originally conceived by Roy Fielding in his 2000 dissertation paper entitled ‘Architectural Styles and the Design of Network-based Software Architectures’, chapter 5 cover REST specifically:
Almost every device that is connected to the internet already uses HTTP; it is the base protocol that the internet is built on which is why it makes such a great platform for an API.
HTTP is a request and response system; a calling client sends a request to an endpoint and the endpoint responds. The client and endpoint can be anything(Mobile App, Desktop App, IOT or Browsers).
There are several key implementation details with HTTP that you should be aware of:
Resources – REST uses addressable resources to define the structure of the API. These are the URLs you use to get to pages on the web, for example,
‘http://www.amazon.com/products’ is a resource
Request Verbs – These describe what you want to do with the resource. A browser typically issues a GET verb to instruct the endpoint it wants to get data, however, there are many other verbs available including things like POST, PUT and DELETE. See the full list at http://www.amazon.com/Protocols/rfc2616/rfc2616-sec9.html
Request Headers – These are additional instructions that are sent with the request. These might define what type of response is required or authorization details. See the full list at http://www.amzon.com/Protocols/rfc2616/rfc2616-sec14.html
Request Body - Data that is sent with the request. For example, a POST (creation of a new item) will require some data which is typically sent as the request body in the format of JSON or XML.
Response Body – This is the main body of the response. If the request was to a web server, this might be a full HTML page, if it was to an API, this might be a JSON or XML document.
Response Status codes – These codes are issues with the response and give the client details on the status of the request. See the full list
REST is an architectural pattern for creating an API that uses HTTP as its underlying communication method. The REST architectural pattern specifies a set of constraints that a system should adhere to. Here are the REST constraints.
Client Server constraint - This is the first constraint. The client sends a request and the server sends a response. This separation of concerns supports the independent evolution of the client-side logic and server-side logic.
Stateless constraint - The next constraint is the stateless constraint. The communication between the client and the server must be stateless between requests. This means we should not be storing anything on the server related to the client. The request from the client should contain all the necessary information for the server to process that request. This ensures that each request can be treated independently by the server.
Cacheable constraint - Some data provided by the server like a list of products, or list of departments in a company does not change that often. This constraint says that let the client know how long this data is good for so that the client does not have to come back to the server for that data over and over again.
Uniform Interface - The uniform interface constraint defines the interface between the client and the server. To understand the uniform interface constraint, we need to understand what a resource is and the HTTP verbs - GET, PUT, POST & DELETE. In the context of a REST API, resources typically represent data entities. Product, Employee, Customer etc are all resources. The HTTP verb (GET, PUT, POST, DELETE) that is sent with each request tells the API what to do with the resource. Each resource is identified by a specific URI (Uniform Resource Identifier). The following table shows some typical requests that you see in an API
Client Server constraint - This is the first constraint. The client sends a request and the server sends a response. This separation of concerns supports the independent evolution of the client-side logic and server-side logic.
Stateless constraint - The next constraint is the stateless constraint. The communication between the client and the server must be stateless between requests. This means we should not be storing anything on the server related to the client. The request from the client should contain all the necessary information for the server to process that request. This ensures that each request can be treated independently by the server.
Cacheable constraint - Some data provided by the server like a list of products, or list of departments in a company does not change that often. This constraint says that let the client know how long this data is good for so that the client does not have to come back to the server for that data over and over again.
Uniform Interface - The uniform interface constraint defines the interface between the client and the server. To understand the uniform interface constraint, we need to understand what a resource is and the HTTP verbs - GET, PUT, POST & DELETE. In the context of a REST API, resources typically represent data entities. Product, Employee, Customer etc are all resources. The HTTP verb (GET, PUT, POST, DELETE) that is sent with each request tells the API what to do with the resource. Each resource is identified by a specific URI (Uniform Resource Identifier). The following table shows some typical requests that you see in an API
|
Resource
|
Verb
|
Outcome
|
|
/Employees
|
GET
|
Gets list of employees
|
|
/Employee/1
|
GET
|
Gets employee with Id = 1
|
|
/Employees
|
POST
|
Creates a new employee
|
|
/Employee/1
|
PUT
|
Updates employee with Id = 1
|
|
/Employee/1
|
DELETE
|
Deletes employee with Id = 1
|
In the context of a REST API, resources typically represent your data entities (i.e. ‘Product’, ‘Person’, ‘Order’ etc). The verb that is sent with the request informs the API what to do with the resource, for example, a GET request gets data about an entity, POST requests create a new entity.
There is a convention in place that GET requests to an entity url such as /Products returns a list of products, possibly matching some criteria that were sent with the request. However, to retrieve a specific product, you would use the product’s ID as part of the resource, for example /Products/81 would return the product with the ID of 81. It is also possible to use query string parameters with an API, for example, you may have something like /Products?Colour=red which returns all red products.
No comments:
Post a Comment