What you need to know about RESTFUL (Architecture/ Design)

RESTFUL (REpresentational State Transfer)

REST is architectural style than programming concept for modern distributed system which comprising 6 basic constraints to fulfill the interface between client requests and server. First, we start with principles belows:

• REST Drives
• REST Properties
• Definition of REST
• REST in architecture and technologies
• Statelessness
• REST Richardson’s Model

REST Drivers

Heterogeneous Interoperability (The way REST can be implemented in any platform)

Assume the news website which load different services from independent external sources and services such as search engine, ads Host , and comments services plus sharing to social medias. All there services have no assumption of how the other services works in your application. That is because of the nature of diversity in technologies, however, the only way to make it work is to have kind of simple, consistent, and reliable. It is clear the architecture would be more network based API than library based API.

Devices

Let’s expand our problem to multiple devices which simply far behind the only phones and tablets for instance, embedded devices, car navigation systems or even microcontroller based gadgets. One common example could be the LED boards which can fetch the latest news and display in public areas. The problem has aroused while this kind of devices using non native operating system or developed in time that there is no consideration for future integration with other services. As result, any kind of communication can make system unstable on one another. Furthermore, It is important to consider the efficiency and performance of devices which rely on the low bandwidth network or low processing and memory constraint hardware.

The Cloud

The cloud is profound part of service provider which is designed to delivered services to different devices via interoperability between wide variety of clients. The cloud helps business to leverage of elasticity of cloud to save money on unused capacities. Regardless on scalability, cloud scalable infrastructure could be critical on those application which not really required Facebook size serieve demands. One of main reason, cloud comes to RESTFUL topic discussion is services which help application to be adjustable based on different devices. For instance, mobile or embedded devices have data usage constraint use different APIs to receive their data. Some other services such as API Gateway, API caching, or serverless functions, play important role in modern API architecture design. The system should design independently from the infrastructure and middleware which avoid cost of configuration, changes and management overhead. Moreover, system need transparency design architecture so when the failure happens, system can diagnosed and rollback efficiently.

What is REST is NOT

• RPC: REST is not a way to call methods over a network without the overhead of SOAP and WSDL and abstract from developers who are using them however, mostly REST design to interact for resources and semantic is not abstracted at all; in fact there made key part of deign.
• HTTP: REST is not HTTP but system are built using HTTP, an architecture implemented on top of HTTP is not inherently RESTful. There are many simple HTTP requests which might not qualify as RESTful service.
• URIs: Alghouth, many frameworks such as MVC and Rails made it easy to work with URLs and routing, many developers spend tremendous time and energy to figure out how would be the perfect URL space when design RESTful service. Hyper-focus could lead to non-RESTful design and revert back the API to RPC.

What is REST?

REST is acronym for REpresentational State Transfer. It is architectural style for distributed hypermedia systems and was first presented by Roy Fielding in 2000 in his famous dissertation. In short, REST is all about style, it is not Protocol or implementation design pattern. REST intended for long-lived web network-based applications or mobile apps.

REST Constraints

Rest compose set of “forces” which taking into account in distributed architecture design such as network reliability, latency, bandwidth, security, network topology, administration, transport cost, heterogeneous network, and complexity of messaging. The below bullet points demonstrate the constraints which architect must consider on design. First we look at constraint itself and then see what forces the constain addresses and at end look at the properties that come up from constraint.

• Client–server
• Improve the portability of user interface on many web and mobile platforms plus scalability by simplifying the server components. This is because of separating the client and server particularly for user interface on different type of devices, such as mobile and tablet, can use same server. in addition, client involve in out impact of services which their consume.
• Influencing Forces:Security- network security of client and server application can scope to be naturally decoupled
• Administration-
• Heterogeneous network- multiple clients run on multiple platform types of languages tools and frameworks can communicate to server without impacting system state on server
• Complexity
• Benefits
• Portability of clients- a lot of type of clients can consume services
• Scalability- simplifying server components to make it easier to add new component as load demands (Microservice)
• Evolvability- client independently uses services
• 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 and maintained entirely on the client.
• Influencing Forces
• Network reliability- storing state on the client and stateless communication to server help client to recover from network errors
• Network topology- client and server can come and go without interrupting the system state
• Complexity- new processing node can be added to system without complex state management
• Administration- handling the visibility of client authentication enable simplifying management on stateless client/server
• Benefits
• Visibility- enable to process each request and responses isolated of one another element in architecture without risking state corruption
• Reliability- This is greatest benefit that stateless can provide, because the state of each request is exist at one point of time. As result, any failure on network and server can be recover in deterministic way. If the problem happen in server can be compensate with last state by client similarly, failure on client can be compensate in server for getting one step back state but not corrupting it entirely. In case of session based system, if failure happen either in server or client the entire process should restart.
• Scalability- The problem of keeping session will make system difficult to be scalable as all the nodes of processing must have access to the shared session all the time.
• 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. The caching can be utilized on browser, company caching/proxy server as intermediate or on anywhere along path from client to server.
• Influencing Forces
• Latency- caching can dramatically reduce latency by eliminating the need to make some requests. That is why important to have labeling on each state that can use cache on client or not.
• Bandwidth- local caching reduces the amount of data that needs to be consumed by the client while intermediary caching reducing the amount of data needed from the origin server.
• Transport cost- caching reduces the total number of network requests needed which led to data charges particular for mobile devices that using network data. Furthermore, server stay in certain level of load before start to scale from additional request which naturally comes with cost or sometime nontrivial cost.
• Benefits
• Efficiency- enable to design more efficient with respect to both latency and bandwidth
• Scalability- system can handle more clients, simply system can scale out for entire network rather that only growing on its own resources.
• Performance
• 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
• hypermedia as the engine of application state.
• Influencing Forces
• Network reliability- consistent semantics increases transparency, enabling clients and servers to more reliably handle failures
• Network topology- providing unified set of constraints governing how clients and servers communicate enables the system elements including intermediaries to be created and evolve independently
• Complexity- the complexity of writing a networked application is constrained to the complexity of uniform interface
• Administration- general management tools can be introduced for optimizing the network
• Heterogeneous network- different client and server can easily interoperate
• Benefits
• Visibility
• Evolvability
• 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. The component in system only knows about components are interacting to them.
• Influencing Forces
• Network topology- Changing network components only impact those elements which involved on network such as load balancer or shared cache server
• Complexity- LImiting the number of components that a component can interact with limits the amount of complexity you can introduce.
• Security- layered network can be potential for security leak vulnerability however, enables intermediaries to be placed at boundaries to manage security policies on that layer for each component.
• Benefits
• Scale
• Manageability — modern web easily implemented no central management, for example client application manage by user, network manage by proxy or internet provider and so on. Although each layer of system manage by different policies, but as result all interfaces communicating in same way. That is why we don’t need know how my browser going interact with my server
• 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.
• Initially described in terms of java applets
• Helps to manage complexity and trade-off of visibility which cause problem to caching or scaling or security
• Find solution to run code on clients which support and keep stability with allowing to progress for those client can’t support it

Elements of RESTful Architecture

• Components and Connectors
• Components
• Origin Server (use same base URL)
• User Agent
• Gateway (cache server/API gateway/ Load Balancer)
• Proxy
• Connectors
• Client
• Server (listen to request and response)
• Cache (store cache)
• Resolver (Translate resource identifier to whatever the right address format such as DNS translate URL to IP). Resolver important in network topology as allows the IP addresses change without breaking connection
• Tunnel (Proxy to connect to SSL)
• Resources Identifier
• Resources require unique identifier
• Identifiers a resources in a component interaction
• The server is responsible for ensuring that mapping semantics between identifier and entities do not change
• Because the identity an abstraction rather than an entity, resource identifiers should change infrequently as possible
• Example: categorise the children in groups or request them individually, so if we want to build RESTful would be in below

• Representations
• Resource state at a point in time
• Can be any sequence of bytes
• A resource can have multiple available representation
• Content negotiation is process of selecting the best representation of a resource
• Control Data
• Represent sort of state which client can request such as data type like JSON or XML or even image for same resource state
• Header will enable to control data
• Hypermedia
• This is the uniform interface constraint that people most often ignore
• Hypermedia as the way to initiate state transition is arguably that most significant differentiator between REST and RPC
• The big idea is to reduce coupling between client and server
• Coupling is reduced by reducing the number of URLs that the client needs to know about

Designing RESTful Services

RESTful Thinking

Regardless of all the knowledge gain on previous sections even to read multiple times, still approach design problem. That is why important to consider the metaphor rather than rely on existing knowledge. One approach is to look at physical world shows example of REST all around us. One question is how would you organize these to facilitate a workflow if we don’t have computer at all?

The simple example can be sticky note board usually use in software development companies. Assume the board divided into multiple columns and sticky notes can move toward columns while the status changed. As result, this scenario has two main elements, Sticky note and board. Now let’s expand it to bug tracking scenario for instance. In order to work efficiently everyone should knows and agreed on format of sticky note such as title, description and flow in board. In our simple example we assume company currently decided to to have backlog, working , done in flow so the board divided into three basic columns. Therefore, when the new bug created it will go to backlog and when team member pickup to fix bug will move to working till the bug fix.

This model can be explained in RESTful flow, however there is a fundamental problem which is how the member need to know the flow. It is necessary that the sticky note explicitly consider the flow which need to follow. In this way RESTful allow us to easily change the workflow and add another step in between like Q/A for example, without having disseminate implicit knowledge throughout team. This is important because communicating this knowledge could be impossible. In addition to add new column in board we update the sticky note as well, this means the team member follow the exact same workflow but this time pass though the Q/A as well. This is really cool feature which RPC fail. This means to make this kind of change you have to version and redeploy whole server and make all clients know to follow the new procedure. In this model, Although the client workflow hasn’t changed at all, the new overall system flow has implemented. In this stage one more things need be done, as new flow implemented all the previous sticky notes must updated with new flow which in word of software is matter of server job to do that in backend process.

Identify the Resources

Let’s back to the same example, Sticky note create as new bug entry and change status in each stage. So this make us believe REST is CRUD over network.

Let’s now design State Transition based on above diagram:

• /bugs- Entry point
• GET: fetch hypermedia elements to navigate and to add a new bug to the backlog
• /bugs/backlog — represent bug that have not yet been activated
• GET: fetch the list of bugs in the backlog
• POST: add a new bug to backlog
• bugs/working — bugs that are being actively worked on
• GET: fetch the list of bugs being worked on
• POST: activate a bug
• bugs/done- bugs that are finish
• GET: fetch the list of bugs that are done
• POST: complete a bug

Design the Representation

In order to plan representation there are few options:

base on Format: (can be anything(XML,JSON,HTML,etc)

State transfer:

• Read only — client does not transfer data to servers
• Predefined- transfer bodies defined in the media type documentation that clients learn to use
• Ad-hoc- details about valid transfer elements are sent to client in the representation (HTML form)

Domain style

• Specific- type is tightly bound to the business domain (custom schema)
• General- type is bound to a general domain, such as invoices or lists (ATOM)
• Agnostic- type is unrelated to specific domain(HTML)

Application Flow

• None- client does not have any flow identifier
• intrinsic- identifiers are built into the media type design
• Applied- identifiers are applied using decorators (HTML rel and class)

Let’s apply these logics to our sticky note bug tracking example :

• Base format = HTML
• State Transfer — As-hoc
• Domain style= Agnostic
• Application Flow= Applied

Need Elements :

• List of bugs
• Link of template for moving a bug to backlog
• Link of template for moving a bug to working
• Link of template for moving a bug to done
• Link template for adding bug
• Navigation links

The key benefit of hypermedia design, not all of these controls are exist for every representation, means when a bug is on backlog state, control only can move it to working state. Similarly, when the bug in working state, control only move it to backlog or done state.

Dynamically Modify the Workflow

As mentioned before, one of best advantages of hypermedia driven API allows dynamically add new state to our workflow. Now let’s see what happen in client and server, If we refer back to our scenario to add QA state to our flow. On the server the new resource will create however, because the client actually doesn’t need to know about URLs it wouldn’t impact on them. The only thing client require to know are some relationships for form class and anchor attribute which is QA. The hypermedia on the working state no long have link to done state and link to new QA state. This design allow the actions on client which are valid to do. All states can be retrieved and dynamically set in client before knowing the meaning of full relationship.

Versioning

In web services, the unit if versioning is the contract==service description == URI -> http://localhost/service/v2/index.php

In REST, the contract is the uniform interface, enabling:

• Versioning within the representation
• Versioning the representation
• Versioning the resource