Outline about RESTful API system

Recently I have been doing RESTful API programming a lot. My understanding about RESTful evolves from “HTTP-Only” request to something more. Below is what I get from recent thoughts.

  1. REST is Representational State Transfer

    It is and only is a design framework for making network communication “web-like.” No specific protocol was proposed, and its main focus was on the communication part. Several questions should be considered during the developement,

    • What are the components of the system?
    • How should they communicate with each other?
    • How do we ensure we can swap out different parts of the system at any time?
    • How can the system be scaled up to serve billions of users?
  2. Client-server

    This is basic system flow of any REST system looks like. It has to be 1-to-1 flow with a centralized resource server. And any other parties who wants to interact with the resources

  3. Stateless

    Most important principle in REST, which means “Each request is treated as a standalone“. In detail, when a client is not interacting with the server, the server has no idea of its existence. The server also does not keep a record of past requests.

  4. Stable identification of resources

    Each resource must be uniquely identified by a stable identifier. A “stable” identifier means that it does not change across interactions, and it does not change even when the state of the resource changes.

  5. Manipulation of resources through representations

    Client manipulates resources through sending representations to the server–usually a JSON object containing the content that it would like to add, delete, or modify. In WEB case, it sends an HTTP POST or PUT request with the content to the server. The server sends back a response indicating whether operation was successful.

  6. Self-descriptive messages

    A self-descriptive message is one that contains all the information that the recipient needs to understand it. In WEB case, for example, request like below

    GET / HTTP/1.1
    Host: www.example.com

    This message is self-descriptive because it told the server what HTTP method was used, and the protocol that was used (HTTP 1.1).

    The server may send back a response like this:

    HTTP/1.1 200 OK
    Content-Type: text/html
    <!DOCTYPE html>
        <title>Home Page</title>
        <div>Hello World!</div>

    This message is self-descriptive because it told the client how it needs to interpret the message body, by indicating that Content-type was text/html.

  7. Hypermedia

    Hypermedia is a fancy word for data sent from the server to the client that contains information about what the client can do next–in other words, what further requests it can make. (Optional)

  8. Cache refers to the constraint that server responses should be labelled as either cacheable or non-cacheable. It should contains in the “self-descriptive message” described mentioned above.
  9. Layered system refers to the fact that there can be more components than just servers and clients. For example, proxy as load balancer, or security checker, authenticator, gateway.
  10. Code on demand works as the ability for a server to send executable code to the client, for example, HTTP server send <script> tag to client to execute locally.