What is REpresentational State Transfer (REST)

REST constraints

For a system to be RESTful, it must satisfy five mandatory constraints:

• It must have a uniform interface to simplify system architecture and improve the visibility of interactions between system components.
• It must incorporate the client-server design pattern, allowing for the separation of concerns and for the client and server implementations to be done independently.
• It must be stateless, meaning that the server and client don't need to know anything about each other's state so they can both understand the messages received from each other without having to see previous messages.
• It must be cacheable, meaning a response should label itself as cacheable or noncacheable, and copies of frequently accessed data must be stored in multiple caches along the request-response path.
• It must be layered to constrain component behavior, to remove the need to edit code (on the client or server) and to improve the web app's security.

In addition, the client system might extend its functionality with the help of code applets or scripts. This constraint in REST is generally known as "code on demand."

REST and the HTTP methods

In a REST system, numerous resource methods are used for resource interactions and to enable resource state transitions. These methods are also known as HTTP verbs.

The default operation of HTTP is GET, used when retrieving a resource or set of resources from the server by specifying the resource ID. In addition to GET, HTTP also defines several other request methods, including PUT (update a resource by ID), POST (create a new resource) and DELETE (remove a resource by ID).

The REST philosophy asserts that to delete something on the server, you would simply use the URL for the resource and specify the DELETE method of HTTP. For saving data to the server, a URL and the PUT method would be used. For operations that are more involved than simply saving, reading or deleting information, the POST method of HTTP can be used.

Advantages of REST

Using the REST architecture for web apps offers the following advantages:

• Resource-based. REST enforces statelessness through resources rather than commands, improving reliability, performance and scalability.
• Simple interface. In REST, each resource involved in client-server interactions is identified and is uniformly represented in the server response to define a consistent and simple interface for all interactions.
• Familiar constructs. REST interactions are based on constructs that are familiar to anyone accustomed to using HTTP, including operations (GET, POST, DELETE, etc.) and URIs. That said, REST and HTTP are not the same and developers must note the differences when implementing and using REST.
• Communication. The status of REST-based interactions between the server and clients is communicated through numerical HTTP status codes. REST APIs use the following HTTP status codes to detect errors and ease the API monitoring process:
• 400 error indicates that the request cannot be processed due to a bad request.
• 404 error indicates that a requested resource wasn't found.
• 401 status response code is triggered by an unauthorized request.
• 200 status response code indicates that a request was successful.
• 500 error signals an unexpected internal server error.

All communications between service agents and components are completely visible, increasing the system's reliability.

• Language-independent. When creating RESTful APIs or web services, developers can employ any language that uses HTTP.
• Widespread use. REST is widely used, making it a popular choice for numerous server- and client-side implementations. For example, on the server side, developers can employ REST-based frameworks like Restlet and Apache CXF, while on the client side, they can employ jQuery, Node.js, Angular or Ember.js, and invoke RESTful web services using standard libraries built into their APIs.
• Web APIs. RESTful services employ effective HTTP mechanisms for caching to reduce latency and the load on servers.
• Separation of client and server. By providing many endpoints, a REST API makes it easy to create complex queries that can meet specific deployment needs. Also, different clients hit the same REST endpoints and receive the same responses if they use a REST interface, improving reliability and performance.
• Resilience. In a REST system, the failure of a single connector or component does not result in the entire system collapsing.

Disadvantages of REST

Its benefits notwithstanding, there are some disadvantages of the REST architecture of which developers should be aware:

• Design limitations. There are some limitations of the REST architecture design. These include multiplexing several requests over a single TCP connection, having different resource requests for each resource file, server request uploads and long HTTP request headers, which cause delays in webpage loading. Also, the freedom that REST provides regarding design decisions can make REST APIs harder to maintain.
• Stateless applications. Because the server does not store state-based information between request-response cycles, the client must perform state management tasks, which makes it difficult to implement server updates without using client-side polling or other types of webhooks that send data and executable commands between apps.
• Definition. REST lacks a clear reference implementation or a definitive standard to determine whether a design can be defined as RESTful or whether a web API conforms to REST-based principles.
• Data overfetching/underfetching. RESTful services frequently return large amounts of unusable data along with relevant information -- typically the result of multiple server queries -- increasing the time it takes for a client to return all the required data.

REST development: URIs and URLs

With the RESTful approach to developing applications, requesting information about a resource state is as simple as invoking its URL.

For example, if a client wanted to invoke a web service that listed all the quizzes available at TechTarget, the URL to the web service would look something like the following:

www.techtarget.com/restfulapi/quizzes

When invoked, the web service might respond with the following JSON string listing all the available quizzes, one of which is about DevOps:

{ "quizzes" : [ "Java", "DevOps", "IoT"] }

To get the DevOps quiz, the web service might be called using the following URL:

www.techtarget.com/restfulapi/quizzes/DevOps

Invoking this URL would return a JSON string listing all the questions in the DevOps quiz. To get an individual question from the quiz, the number of the question would be added to the URL.

So, to get the third question in the DevOps quiz, the following RESTful URL would be used:

www.techtarget.com/restfulapi/quizzes/DevOps/3

Invoking that URL might return a JSON string such as the following:

{ "Question" : {"query":"What is your DevOps role?", "optionA":"Dev", "optionB":"Ops"} }

In the above example, the REST URLs are structured in a logical and meaningful way that identifies the exact resource being requested.

JSON and XML REST data formats

In REST, the two most common data exchange formats are JSON and XML. Many RESTful web services can use both formats interchangeably, as long as the client can request the interaction to happen in either format.

Note that while JSON and XML are popular data exchange formats, REST itself does not put any restrictions on what the format should be. In fact, some RESTful web services exchange binary data for the sake of efficiency. This is another benefit to working with REST-based web services, as software architects have a lot of freedom to decide how best to implement a RESTful service.

Developing REST APIs in Java

To accommodate the growing popularity of REST-based systems, there are several frameworks to help developers create RESTful web services. Some of the more popular open source frameworks for creating Java-based, RESTful web services include Apache CXF, Jersey, Restlet, Spring Data and JBoss RESTEasy.

The general approach of these frameworks is to help developers build RESTful web services using semantics that are familiar to Java developers, including Java Platform, Enterprise Edition (J2EE) Servlet API and annotations, while also offering built-in classes and methods that make it easier to conform to the basic tenets of REST.

Alternatives to REST

REST makes it easy to implement network-based web services by using the basic construct of the network protocol itself, which in terms of the internet is HTTP. Thus, there's no need for developers to work with custom protocols for client-server message exchanges. That's important, as REST and its principles are intended to apply not just to the internet, but to apply to all protocols, including WebDAV and FTP.

That said, REST is mainly a good fit for CRUD (create, read, update, delete) applications where the five HTTP methods (GET, PUT, POST, PATCH, DELETE) can be easily used. For other types of applications or use cases, REST might not be the best choice. Examples include apps that require persistent stateful connections to be maintained, apps that rely on (or retrieve) complex interconnected data, alerting apps or apps like live chats or collaborative workspaces.

For those and other applications, these following alternatives might be better than REST:

• GraphQL.
• gRPC.
• MQTT.
• WebSocket.

Furthermore, for creating SOA-based systems or creating APIs for invoking remote microservices, technologies like XML over HTTP (XML-RPC), CORBA, RMI over IIOP and the Simple Object Access Protocol (SOAP) might be better choices than REST.

REST vs. SOAP

REST and SOAP are both used for implementing web services. The fundamental difference between them is in their approach to remote invocations. REST takes a resource-based approach to web-based interactions. With REST, you locate a resource on the server and you choose to update that resource, delete it or get some information about it. With SOAP, the client doesn't interact directly with a resource, but instead calls a service, which then mediates access to the various objects and resources.

SOAP has also built many frameworks and APIs on top of HTTP, including the Web Services Description Language (WSDL), which defines the structure of data that gets passed back and forth between the client and the server.

Some problem domains are served well by the ability to stringently define the message format or might benefit from using various SOAP-related APIs, such as WS-Eventing, WS-Notification and WS-Security. In some situations, HTTP cannot provide the level of functionality an application might require, so using SOAP is preferable.

REST and the IoT

In an internet of things (IoT) environment, devices work in a client-server relationship and can act as clients, servers or both. As a client, an IoT device can initiate contact with a directory, such as the CoRE Resource Directory, or another device, while as an origin server or resource, it can serve as a temperature or other type of sensor.

The near ubiquity of REST APIs and the expanding number of devices on the IoT makes REST a suitable architectural choice for IoT. Also, the data requested from resources in IoT tends to be simple (e.g., a sensor's current reading) and static (e.g., a manufacturer's device description), making REST -- which utilizes the internet's HTTP -- a natural fit. Thirdly, on the IoT, compact formats based on JSON, EXI and CBOR (Concise Binary Object Representation -- a JSON offshoot) are used. RESTful APIs are likewise compact, again making them suitable for IoT applications.

History of REST

REST was first developed by computer scientist Roy Thomas Fielding in 2000 as part of his Ph.D. dissertation at the University of California, Irvine, titled Architectural Styles and the Design of Network-based Software Architectures.

Chapter 5 of the dissertation, Representational State Transfer (REST), described REST as an architectural style for distributed hypermedia systems. In this chapter, Fielding noted the five conditions described previously that define how RESTful systems should behave.