In this article you will understand Roy Fielding’s theory, which described the software architecture most used today for building APIs and integrating systems in the cloud, REST (Representational State Transition), which served as the basis for the APIs of modern software in the cloud ( or in cloud if you prefer).
In addition to this article, as complementary material, a video lesson is available that deals with REST API concepts and slides for follow-up.
Complementary material
Download - Slides - Restful-presentation
The video lesson is divided into three parts, the links are in the description of each video and on the final cards.
Basic concepts about REST, RESTful and APIs
What is an API - quick definition
Initially a quick and explanatory definition about: What are APIs?
API - Application Programming Interface, is a set of routines and standards established by a software for the use of its functionalities by applications, therefore, they do not need to get involved in implementation details, and rather just use (consume) its services.
The following APIs can be considered:
* the interfaces of a programming library or framework, for example, the API of the language [PHP](/en/php/) or the
framework Laravel; * the interfaces of a locally available program, for example, the API of the suite LibreOffice or the Imagick software that runs via the command line; * or the most commonly cited today, Web communication interface, such as a Web Service, to use or make available various services, for example, Google API, Twitter, Facebook, [SalesForce](https://developer.salesforce.com/ docs/api-explorer), etc.
Web services
One more concept quickly explained: Web Service (WS), is a service offered by an electronic device to another electronic device, for example, two cloud systems. Both communicate with each other via the World Wide Web.
Saying in another way, a server running on a computer device, listening for requests on a specific network port, serving web documents (HTML, JSON, XML, images) and creating web application services, which serve in resolving specific domain problems on the Web (WWW, Internet, HTTP).
In a Web Service, a Web technology such as HTTP-protocol is used to transfer machine-readable file formats such as XML and JSON.
REST - definition
REST - REpresentational State Transfer: is an architectural style for distributed hypermedia systems, first presented by Roy Fielding in 2000 in his doctoral thesis , named “Architectural Styles and the Design of Network-based Software Architectures”.
Like any other architecture style, REST defines its own guiding constraints, that is, architectural principles, 6 in number, that must be satisfied if an interface - API, needs to be defined as RESTful.
Guiding Principles of REST
1. Client/Server
By separating the UI issues, i.e. - UX or User eXperience, from the data storage issues, i.e. the logic of managing and persisting the data and information, we improve the portability of the UI across multiple platforms and improve scalability by simplifying server components.
2. Stateless
Each request from the client to the server must contain all the information necessary to understand the request and cannot take advantage of any context stored on the server. Session state is therefore maintained entirely on the client.
3. Cacheable
Cache constraints require that data in a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable.
If a response can be cached, the client cache has the right to reuse the response data for equivalent requests later.
4. Uniform interface
By applying the Software Engineering principle of generality to the component interface, the overall architecture of the system is simplified and the visibility of interactions is improved.
To achieve a uniform interface, several architectural constraints are needed to guide the behavior of components.
REST is defined by four interface constraints:
- resource identification;
- manipulation of resources through representations;
- self-describing messages;
- hypermedia as the application’s state engine.
5. Layered system
The layered system style allows an architecture to be composed of hierarchical layers, constraining the behavior of components so that each component cannot “see” beyond the immediate layer it is interacting with.
Code on demand
*optional
REST allows client functionality to be extended by downloading and running code in the form of applets or scripts. This simplifies customers by reducing the number of features required to be pre-deployed.
Resource in API
The key abstraction of information in REST is resource.
Any information that can be named can be a resource, for example: a document or image, a temporary service, a collection of other resources, a non-virtual object (for example, a person) and so on.
REST uses a resource identifier to identify the particular resource involved in an interaction between components.
The state of the resource at any particular timestamp (time stamp) is known as the resource representation.
Namely, a representation consists of data, metadata describing the data, and hypermedia links that can help clients transition to the next desired state.
The data format of a representation is known as the media type.
The media type identifies a specification that defines how a representation is to be rendered.
A truly RESTful API looks like hypertext.
Each addressable unit of information carries an address, either explicitly, for example, link and id attributes - or implicitly, for example, derived from the media type definition and representation structure.
Resource – according to Roy Fielding
Hypertext (or hypermedia) means the simultaneous presentation of information and controls in such a way that the information becomes the resource through which the user (or automaton) obtains choices and selects actions.
Remember that the hypertext does not have to be HTML (or XML or JSON) in a browser. Machines can follow links when they understand the data format and relationship types. – Furthermore, resource representations must be self-describing: that is, the client does not need to know whether a resource is an employee or a device. It must act based on the media type associated with the resource. So, in practice, you’ll end up creating many custom media types - typically a media type associated with a resource.
Each media type defines a default rendering model. For example, HTML defines a rendering process for hypertext and browser behavior around each element.
Also, REST architecture theory has no bearing on resource methods GET / PUT / POST / DELETE / … other than the fact that some media type elements will define a process model that works like for example:
- anchor elements, with an
hrefattribute, create a hypertext link that, when selected, invokes a retrieve (GET) request - on the URI corresponding to the
CDATA/ encodedhrefattribute.
Resource Methods
Also associated with REST are resource methods to be used to accomplish the desired transition. A large number of people incorrectly relate resource methods to HTTP methods (verbs): GET / PUT / POST / DELETE.
In principle, Roy Fielding never mentioned any recommendations about which method to use in which condition. All he emphasizes is that there must be a uniform interface.
If you decide that HTTP POST will be used to update a resource - instead of what most people recommend HTTP PUT - that’s
fine and the app’s interface will be RESTful.
Ideally, everything needed to change the resource’s state should be part of the API response for that resource - including methods and what state they’ll leave the representation in after calling them.
Resource Methods – by Roy Fielding
A REST API must be entered with no prior knowledge other than the initial URI (placeholder) and set of standardized media types that are appropriate for the target audience (i.e. must be understood by any client that might use the API).
From that point on, all application state transitions must be driven by the client’s selection of server-supplied options that are either present in the received representations or implied by the user’s manipulation of those representations.
Transitions can be determined (or constrained) by the customer’s knowledge of media types and resource communication mechanisms, both of which can be improved on the fly, eg code on demand. This means that, the failure here implies that out-of-scope information is driving the interaction rather than hypertext. –
Another thing that will help you when building RESTful APIs is that query-based API results should be represented by a list of links with summary information, not arrays of original resource representations because the query does not replace the resource ID.
REST and HTTP are not the same thing
Many people prefer to compare HTTP with REST. REST and HTTP are not equals.
However, as REST is also intended to make the web (internet) simpler and more standardized, he advocates using REST principles more strictly. This is where people tend to compare REST to the web (HTTP). Roy Fielding, in his dissertation, nowhere mentioned any implementation directives - including any protocol preferences and HTTP.
This means that if you adhere to the 6 guiding principles of REST, you can call your API RESTful.
In other words, in the REST architectural style, data and functionality are considered resources and are accessed using Uniform Resource Identifiers (URIs).
Resources are triggered through a set of simple, well-defined operations.
Clients and servers exchange resource representations using a standardized interface and protocol - usually HTTP.
Resources are separated from their representation so their content can be accessed in a variety of formats such as HTML, XML, plain text, PDF, JPEG, JSON and others.
Metadata about the resource is available and used, for example, to control caching, detect transmission errors, negotiate the appropriate representation format, and perform authentication or access control.
Most importantly, every interaction with a resource is stateless.
Anyway, all these principles help RESTful applications to be simple, light and fast.
Comments