Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

What Does RESTful Really Mean?

DZone's Guide to

What Does RESTful Really Mean?

A deep dive into the definition of REST, constraints, and pros and cons.

· Integration Zone
Free Resource

Discover how developers can easily discover existing APIs and back-end data sources and create new APIs and microservices based on the popular open-source Node.js Express and LoopBack® frameworks.  Brought to you in partnership with IBM.

Last month, I attended Fast Track to RESTful Microservices training at Skillsmatter. During the course, we explored what REST APIs can offer to web applications in general and microservices communication in particular. Personally, the most important outcome of the course is a better understanding of what REST really means and what are its pros and cons.

During most of my career, I've been focused on mobile technologies, and therefore on the consuming side of web APIs. Most APIs that I've ever consumed were supposed to be RESTful, but now that I better understand what RESTful means I can say that 99% of them weren't even close to RESTful (clients are broken because of something being added in the server side sound familiar?).

Definition

The term REST stands for "REpresentational State Transfer." A possible formal definition of it could be as follows.

Architectural API style based on transferring a representation of state (documents) between client and server in order to progress the state of an application.

Constraints

To consider applications as RESTful, applications need to conform to the following REST constraints. Complying with the constraints enables a distributed hypermedia system to have the following desirable non-functional properties: performance, scalability, simplicity, extensibility, visibility, portability, and reliability.

Client-server

A client-server model favors separation of concerns so that clients are not concerned with data storage. Thus, clients code portability is improved. On the other hand, the server is not concerned about user interface or user state, so that server can be simpler and more scalable. Servers and clients can be developed independently, as long as they conform to the defined contract.

Stateless

Client context is never stored on the server between requests. Each request has to contain all the necessary information. A stateless server improves scalability by allowing the server to quickly free resources and simplifies implementation. Reliability eases recovering from partial failures. Visibility, monitoring system does not have to look beyond a single request to determine the nature of the request.

One of the drawbacks of having a stateless server is decreased network performance, as all the needed data has to be sent in each request.

Cacheable

REST applications are web systems; therefore, clients and intermediaries can cache responses. Responses themselves must be defined as cacheable, or not, to prevent clients from reusing stale data that could reduce reliability. If stale data in the cache differs significantly from the data that would have been generated the request been handled by the server. Caching could eliminate some client-server interaction, thus improving scalability, efficiency, and user-perceived performance by reducing average latency.

Uniform interface

Using a uniform interface simplifies and decouples the architecture and favors the independent evolution of different parts. As explained later on in this post, URIs, resources and hypermedia help to produce a standard interface that improves the visibility of interactions, simplifies the overall system architecture and encourage independent evolution. The trade-off is that it degrades efficiency since information is transferred in a standard format rather one which is particular to an application's needs.

Layered system

Using a layered system reduces complexity by constraining component behavior such that each element cannot access beyond its immediate layer. Favors substrate independence by restricting knowledge of other parts of the system. Layers can encapsulate legacy components and protect new services from legacy clients. Intermediaries can be used to improved scalability by enabling load balancing across networks. The main trade-off is that layered systems add overhead and latency to the data processing, therefore, reducing user-perceived performance.

Code-On-Demand (Optional)

REST allows clients to extend their functionality by downloading and executing code scripts. This simplifies clients and improves extensibility. On the other hand, it reduces visibility, which is why it is only an optional constraint.

Elements

REST has several elements in its toolbox to build stateless, scalable and simple web APIs.

  • HTTP
  • Resources
  • URIs
  • Hypermedia

HTTP - Document Transfer Application Protocol

REST is usually used along with HTTP as its transfer protocol as it offers several advantages. Among them are HTTP verbs, status codes, and headers.

Verbs

Instead of defining new verbs for every possible behaviour in our web service, HTTP introduces a standard set of verbs to handle similar situations in the same way, removing unnecessary variation and creating a more intuitive API. Each verb has a different combination of two properties that make them suitable for different scenarios.

  • Idempotent: The operation can be repeated in the event of failures.
  • Safe: The operation has no side-effects for which the client is responsible.
  • GET

    Used to read state from the server. Being a safe operation, it can be executed multiple times without risk of data modification or corruption - calling it once has the same effect as calling it ten times. As an idempotent operation, making multiple identical requests has the same result as a single request.

    POST

    Usually used to create some state on the server. It's neither safe nor idempotent. Therefore multiple requests will create several resources on the server. As a non-idempotent operation, POST should not be used for operations that deal with money, as in the case of a failed request is done multiple times, we would potentially be transferring money or paying multiple times.

    PUT

    It's mostly used to update state on the server, although it can also be used to create state. It's Idempotent but not safe as it changes the state of the server. Being an idempotent made PUT a good candidate, for instance, for operations related to money.

    DELETE

    It's used to delete state on the server. It's idempotent but not safe, as it removes state from the server. It's idempotent as deleting state that has previously been deleted should not have further implications.

    Response Status Codes

    The HTTP status codes provide metadata in the response to the state of the requested resources. They are part of what makes The Web a platform for building distributed systems. They are divided into the following categories:

    • 1xx — Metadata.
    • 2xx — Everything is fine.
    • 3xx — Redirection.
    • 4xx — Client did something wrong.
    • 5xx — Server did something wrong.

    Headers

    The HTTP headers are components to pass additional information in requests and responses. Headers consist of a case-insensitive name followed by a colon and its value. Headers could be grouped as:

    • General headers: Apply to both requests and responses but there is no relation to the data transmitted in the body.
    • Request headers: Contain more information about the resource being fetched or about the client making the request.
    • Response headers: Contain additional information about the response.
    • Entity headers: Add information about the body of the entity, like content-length or MIME-type.

    Resources

    A resource is anything exposed by the system that has an identity. Resources offer a way to adapt the application domain to web clients. An image, a spreadsheet, a service or a collection of other resources are some resource examples. The resources are fetched or send using a certain representation (XML, JSON, etc.).

    We deal with resources representations, not with the resources themselves, following the idea of "Pass-by-value." Following the previous REST definition, resources represent the documents being transferred across the network to get work done. Resource state is a server-side concern, as it represents the domain state, clients only fetch or send resource representations to progress the application state. On the other hand, application state is a client-side concern as it represents the progress towards a particular application goal.

    Resources should be named as nouns as they represent concepts in the domain of a particular system and are identified using URIs.

    URIs (Uniform Resource Identifiers)

    URIs differentiate one resource from another. To access and manipulate a resource, it needs to have at least one address. They are composed of a protocol + host + path.

    Clients should not be coupled to particular resources URIs as they can be changed at server's discretion. This is where hypermedia has the greatest advantages, as it offers a way to decouple clients from specific URIs and add semantics to the application protocol.

    Hypermedia

    Hypermedia informs the client about what it can do next, through the use of hypermedia controls (links and forms) in the responses, and the particular URI to do it. The concrete hypermedia format for a particular application is defined in the application Media Type.

    Hypermedia links are composed by a href attribute that specifies the URI to access the linked resource and a rel attribute that defines the meaning of the relationship, therefore, adding semantics to the state transitions in the application. The use of links allows the server to advertise new capabilities by including new links in the responses without breaking existing clients. As long as the server maintain previously defined links in the responses, clients would be able to follow them just as they were before the new state was added. Clients would need to be updated only if they need to access the new state. Another hypermedia advantage is that it introduces discoverability by providing a way of making a discoverable and self-documenting protocol.

    Clients start interacting with the app through a fixed URL, and from thereon all further actions happen by the client following the links, formatted using the media type, and provided by the server in each response.

    Media types and links define the contract between the application server and the client. The client interacts with the system by navigating the application state using the links. This is what HATEOAS (Hypermedia as the engine of application state) really means.

    Hypermedia (in addition to the already defined elements) is what RESTful really means.

    Richardson Maturity Model

    This model has helped me a lot to understand what REST means and how to explain the properties of a web application. It divides the components of a REST system into three levels and provides a way to understand the ideas, concepts and the advantages of RESTful thinking. I'd say that it's an educational model rather than an assessment mechanism.

    A detailed explanation of what Richardson Maturity Model is can be found at Martin Fowler's blog.

    This article was first published on the Codurance blog.

    Learn about the comprehensive capabilities to create, run, manage, secure and monetize APIs and microservices with API Connect.  Brought to you in partnership with IBM.

    Topics:
    restful ,rest api

    Published at DZone with permission of Carlos Morera, DZone MVB. See the original article here.

    Opinions expressed by DZone contributors are their own.

    The best of DZone straight to your inbox.

    SEE AN EXAMPLE
    Please provide a valid email address.

    Thanks for subscribing!

    Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
    Subscribe

    {{ parent.title || parent.header.title}}

    {{ parent.tldr }}

    {{ parent.urlSource.name }}