REST (REpresentatation State Transfer)

  • REST is an architectural style that defines a set of constraints to be used for creating Web services. Conformant services are known as RESTful Web services, and provide interoperability between computer systems on the internet.
  • RESTful Web services allow the requesting systems to access and manipulate textual representations of Web resources by using a uniform and predefined set of stateless operations.
  • In a RESTful Web service, requests made to a Web resource's URI will elicit a response with a payload formatted in HTML, XML, JSON or some other format.
    • The response can confirm that some alteration has been made to the stored resource, and the response can provide hypertext links to other related resources or collections of resources.
    • When HTTP is used, as is most common, the operations (HTTP methods) available are:

    REST HTTP Methods

    HTTP Method Collection resource
    https://api.com/items/
    Member resource
    https://api.com/items/item3/
    GET Retrieve the URIs of the member resources of the collection in the response body. Retrieve representation of the member resource in the response body.
    POST Create a member resource in the collection resource using the instructions in the request body. The URI of the created member resource is automatically assigned and returned in the response Location header field. Create a member resource in the member resource using the instructions in the request body. The URI of the created member resource is automatically assigned and returned in the response Location header field.
    PUT Replace all the representations of the member resources of the collection resource with the representation in the request body, or create the collection resource if it does not exist. Replace all the representations of the member resource or create the member resource if it does not exist, with the representation in the request body.
    DELETE Delete all the representations of the member resources of the collection resource. Delete all the representations of the member resource.
    PATCH Update all the representations of the member resources of the collection resource using the instructions in the request body, or may create the collection resource if it does not exist. Update all the representations of the member resource, or may create the member resource if it does not exist, using the instructions in the request body.

    Non REST Methods

    HTTP Method Description
    CONNECT

    Starts two-way communications with the requested resource. It can be used to open a tunnel.

    For example, the CONNECT method can be used to access websites that use SSL (HTTPS). The client asks an HTTP Proxy server to tunnel the TCP connection to the desired destination. The server then proceeds to make the connection on behalf of the client. Once the connection has been established by the server, the Proxy server continues to proxy the TCP stream to and from the client.

    CONNECT is a hop-by-hop method.

    OPTIONS

    The OPTIONS method is used to describe the communication options for the target resource. The client can specify a URL for the OPTIONS method, or an asterisk (*) to refer to the entire server.

    TRACE

    The TRACE method performs a message loop-back test along the path to the target resource, providing a useful debugging mechanism.

    The final recipient of the request should reflect the message received, excluding some fields described below, back to the client as the message body of a 200 (OK) response with a Content-Type of message/http. The final recipient is either the origin server or the first server to receive a Max-Forwards value of 0 in the request.

  • By using a stateless protocol and standard operations, RESTful systems aim for fast performance, reliability, and the abiity to grow by reusing components that can be managed and updated without affecting the system as a whole, even when it is running.
  • The term representational state transfer is intended to evoke an image of how a well-designed Web application behaves: it is a network of Web resources (a virtual state-machine) where the user progresses through the application by selecting resource identifiers such as http://www.example.com/articles/21 and resource operations such as GET or POST (application state transitions, resulting in the next resource's representation (the next application state)being transfered to the end user for their use.
  • Put vs Patch
  • Representational state transfer
  • What is a REST API
  • REST API Tutorial

Architectural constraints

Six guiding contraints define a RESTful system. These constraints restrict the ways that the server can process and respond to clients requests so that, by operating within these constraints, the system gains desirable non-functional properties, such as performance, scalability, modifiability, visibility, portability and reliability. If a system violates any of the required constraints, it cannot be considered RESTful.

  1. Client-server architecture

    This is about separation of concerns. Separating the user interface concerns from the data storage concerns improves the portability of the user interfaces across multiple platforms. It also improves scalability by simplifying the server components. Perhaps the most significant to the Web, however is that the separation allows the components to evolve independently, thus supporting the Internet-scale requirement of multple organizational domains.

  2. Statelessness

    The client server communication is constrainted by no client context being stored on the server between requests. Each request from any client contains all the information necessary to service the request, and the session state is held in the client. The session state can be transferred by the server to another service such as a database to maintain a persistent state for a period and allow authentication. The client begins sending requests when it is ready to make the transition to a new state. While one or more requests are oustnding, the client is considered to be in transition. The representation of each application state contains links that can be used the next time the client chooses to initiate a new state-transition.

  3. Cacheability

    As on the World Wide Web, clients and intermediaries can cache responses. Responses must therefore, implicitly or explicitly, define themselves as cachable or not to prevent clients from getting stale or inappropriate data in response to further requests. Well-managed caching partially or completely eliminates some client-server interactions, further improving scalability and performance.

  4. Layered system

    A client cannot ordinarly tell whether it is connected directly to the end server, or to an intermediary along the way. This means that the client doesn't know if it's talking with an intermediate or the actual server. So if a proxy or load balancer is placed between the client and the server, it wouldn't affect their communications and there wouldn't be necessities to update the client or server code. Intermediary servers can improve system scalability by enabling load balancing and by providing shared caches. Also, security can be added as a layer on top of the web services, and then clearly separate business logic from security logic. By adding security as a separate layer enforces security policies. Finally, it also means that a server can call multiple other servers to generate a response to the client.

  5. Code on demand (optional)

    Servers can temporarily extend or customize the functionality of a client by transferring executable code: for example, compiled components such as Java applets, or client-side scripts such as JavaScript.

  6. Uniform interface

    The uniform interface constraint is fundamental to the design of any RESTful system. It simplifies and decouples the architecture, which enables each part to evolve independently. The four constraints for this uniform interface are:

    1. Resource and identification in requests

      Individual resources are identified in requests, for example using URIs in RESTful Web services. The resources themselves are conceptually separate from the representations that are returned to the client. For example, the server could send data from its database as HTML, XML or as JSON - none of which are the server's internal representation.

    2. Resource manipulation through representations

      When a client holds a represenatation of a resource, including any metadata attached, it has enough information to modify or delete the resource.

    3. Self-descriptive messages

      Each mesage includes enough information to describe how to process the message. For example, which parser to invoke can be specified by a media type.

    4. Hypermedia as the engine of application state (HATEOAS)

      Having accessed an initial URI for the REST application - analogous to a human web user accessing the home page of a website - a REST client should then be able to use server-provided links dynamically to discover all the available actions and resources it needs. As the access proceeds, the server responds with text that includes hyperlinks to other actions that are currently available. There is no need for the client to be hard-coded with information regarding the structure or dynamics of the application.




Many developers also describe their APIs as being RESTful, even though these APIs actually don't fulfill all of the architectural constraints described above (especially the uniform interface constraint).




One problem with REST is the Maximum characters in an HTTP request header value. The default is 4096. This can become a blocker causing some devs to just use POST in all cases :O.

This is because its maximum body size is usually in the range of 1MB to 2GB.

Other APIs

SOAP vs REST
Difference SOAP REST
Style Protocol Architectural Style
Function Function-driven: transfer structured information Data-driven: access a resource for data
Data format Only uses XML Permits many data formats, including plain text, HTML, XML, and JSON
Security Supports WS-Security and SSL Supports SSL and HTTPS
Bandwidth Requires more resources and bandwidth Requires fewer resources and is lightweight
Data cache Can not be cached Can be cached
Payload handling Has a strict communication contract and needs knowledge of everything before any interaction Needs no knowledge of the API
ACID (Atomicity, Consistency, Isolation, Durability) Compliance Has built-in ACID compliance to reduce anomalies Lacks ACID compliance
GraphQL vs REST