RESTful Web Services

REST API:https://www.kennethlange.com/rest-api-checklist/

6 Rules that must be satisfied so that an Web service Interface (API) can be considered RESTful.

Desirable properties: scalability, decoupling, simplicity.

These constraints already apply to HTTP 1.1 and the URI Syntax.

Why is it called REST?

REST = REpresentational State Transfer

The server has resources.

We transfer the representation (a description, usually JSON) of the state (actual data) of resources (files) to the client and back.

When the client has received the representation it can update it, and send the updated representation back to the server.

Client can request a description of the Data on the Server over an API.

6 REST Constraints

1. Client Server

Seperation of concerns in System = clients + servers

Server back-end (data storage, business rules, etc.)

Client front-end (user interfaces, user experience, etc.)

Most common protocol is HTTP but one could use any other.

2. Stateless

No context information.

There should be no browser cookies, session variables / other stateful features.

Each request must contain all the information necessary to perform the request.

3. Cache

Responses from servers must be marked as cacheable or noncacheable.

4. Uniform Interface

Decouples the interface from actual implementation.

  1. Identification of Resources

    A resource is basically anything that can be named. (good naming for URI path)

    (On implementation level usually = database tables)

    Identifier must be stable even when the underlying resource is updated.

  1. Manipulation of Resources through Representations

    Client does not interact directly with the server’s resource but a representation of the resource’s state = we show the resource’s data / state in a neutral format, usually JSON.

  1. Self-Descriptive Messages

    Each message must have a media type (ie.application/json,application/xml) that tells the receiver how the message should be parsed.

    HTTP is not formally required for RESTful web services, but if you use the HTTP methods you should follow their formal meaning. (ie. not using POST to retrieve data, GET to save data,...)

    The usage of the API with HTTP method and URI paths should be intuitive to use.

  1. Hypermedia as the Engine of Application State (HATEOAS)

    A webpage is an instance of application state and hypermedia is text with hyperlinks.

    We should use links to navigate through the application (states) - no need to read API documentation to navigate.

5. Layered System

Abstraction: The client should only know the immediate layer it is communicating with from the server.

Client doesn’t need to know if it’s talking with an intermediate or the actual server: proxy, load balancer, security as a layer etc. wouldn't affect communication.

6. Code-On-Demand (Optional)

A server can send client code that it should execute (like Java Applets, or JavaScript).

Extends the functionality of the client / the browser on runtime.

Very uncommon in REST APIs but in webpages this is very common.