RESTful API
REST
The Representational State Transfer (REST) architectural style is not a technology you can purchase or a library you can add to your software development project. It is first and foremost a worldview that elevates information into a first-class element of the architectures we build.
The summary of the approach is that by making specific architectural choices, we can elicit desirable properties from the systems we deploy. The constraints detailed in this architectural style are not intended to be used everywhere, but they are widely applicable.
What does Representational State Transfer mean? Transferring, accessing, and manipulating textual data representations in a stateless manner. When deployed correctly, it provides uniform interoperability, between different applications on the internet. The term stateless is a crucial piece to this as it allows applications to communicate agnostically. A RESTful API service is exposed through a Uniform Resource Locator (URL). This logical name separates the identity of the resource from what is accepted or returned.
REST abstractions:
Resource is a key abstraction that HTTP centers round. A resource is anything you want to expose to the outside world, through your application. For instance, if we write a todo management application, instances of resources are:
A specific user
A specific todo
A list of todos
Resource URIs
When you develop RESTful services, you need to focus your thinking on the resources in the application. The way we identify a resource to expose, is to assign a URI - Uniform Resource Identifier - to it. For example:
The URI for the user John is
/user/John
The URI for all the todos belonging to John is
/user/John/todos
The URI for the first todo that John has is
/user/John/todos/1
Resource Representation
REST does not worry about how you represent your resource. It could be XML, HTML, JSON or something entirely different! The only important thing is you clearly define your resource, and perform whatever actions that are supported on it by making use of features already provided by HTTP. Examples are:
Create a user:
POST /users
Delete a user:
DELETE /users/1
Get all users:
GET /users
Get a single user:
GET /users/1
Architecture:
Endpoint is the identity of a resource. Server determines shape & size of the resource to be sent to client.
REST API provides a list of endpoints. Different HTTP verbs as GET, POST, PUT, DELETE, PATCH are used to describe client-server communications.
API requests are handled by route handling functions that are matched by URL path & HTTP verb. Result, produced by a function is serialized & sent back to client with appropriate headers & HTTP status codes.
Guiding Principles of REST
Client–server – By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.
Stateless – Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
Cacheable – Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
Uniform interface – 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. In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.
Layered system – The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.
Code on demand (optional) – REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.
Richardson Maturity Model
In part to help elucidate the differences between SOAP and REST, and to provide a framework for classifying the different kinds of systems many people were inappropriately calling “REST,” Leonard Richardson introduced a Maturity Model. You can think of the classifications as a measure of how closely a system embraces the different pieces of Web Technology: Information resources, HTTP as an application protocol, and hypermedia as the medium of control.
LEVEL
ADOPTION
0
This is basically where SOAP is. There are no information resources, HTTP is treated like a transport protocol, and there is no concept of hypermedia. Conclusion: REST and SOAP are different approaches.
1
URLs are used, but not always as appropriate information resources, and everything is usually a GET request (including requests that update server state). Most people new to REST first build systems that look like this.
2
URLs are used to represent information resources. HTTP is respected as an application protocol, sometimes including content negotiation. Most Internet-facing “REST” web services are really only at this level because they only support non- hypermedia formats.
3
URLs are used to represent information resources. HTTP is respected as an application protocol including content negotiation. Hypermedia drives the interactions for clients.
Last updated
Was this helpful?