REST: Representational State Transfer

REST (Representational State Transfer)

• REST is an architectural style for distributed systems.
• It relies on transferring representational state.
• It is a model for web service design.
• REST controls interaction of four web participants which are servers, gateways, proxies, and clients.
• REST consists of clients and servers.
• Clients initiate requests to servers.
• Servers respond to requests, returning responses.
• Requests/responses involve transference of resource representations.
• A resource is defined as a concept with meaning or an entity.
• Representation is a document with the state of a resource.
• Requests indicate a change of state from the client.
• REST is similar to approaches like SOAP.
• It uses loose coupling.
• It is not strongly typed.
• REST more bandwidth efficient.
• REST uses verbs and nouns which makes it readable.

Goals of REST

• Scalability.
• Easy and portable/general interfaces.
• Loosely coupled components.
• Intermediary components for security, latency, etc.

REST constraints

• Client-server architecture with uniform, isolated, and strictly encapsulated interface.
• Stateless: Server doesn't store client state (stored on client).
• Cacheable: Clients can cache responses; responses must include caching control information.
• Layered: Intermediate layers are transparent to clients.
• Optional client-side code injection where the server can send code to extend client (Javascript).
• Uniform interface between clients and servers.

REST and HTTP

• REST (HTTP) functions as a state machine with states being web pages.
• Transitions are fired by buttons/links.
• State (pages) are transferred from server to client.

REST Vocabulary

• Includes standard HTTP verbs: GET, POST, HEAD, PUT, DELETE
• REST does not depend on the application.

SOAP and other RPC

• Each application defines its vocabulary.
• Example: GetAmount(), GetEquipoByGrupoTemporada(string sNomFuncion, string sNomCampo, int iGrupo, int iTemporada)
• Not limited by "HTTP" vocabulary and can work on other transports like TCP, UDP, etc.
• It must publish a more detailed API specification (WSDL, etc.).
• Individual resource identification is required in requests and representation is then transferred (JSON, HTML, etc.).
• Clients only have a representation to work with.
• All needed data and metadata must be included.
• Messages are self-contained including MIME type, cache information, encoding, etc.
• HATEOAS (Hypermedia As The Engine Of Application State): Actions are identified only through hyperlinks (except entry points).

Core idea

• REST depends on existence of resources uniquely referenced by a URI.
• Agents (client, server) use a standard interface (HTTP) to exchange representations (XML, JSON) of these resources statelessly.

REST/RESTful translated for programmers

• Everything should have a unique ID.
• Link entities (HREF).
• Only use standard methods like GET, POST, HEAD.
• Utilize multirepresenting resources (.xml, .json, .html, ...).
• Stateless communication

RESTful Web Service

• RESTful is a web service implemented over HTTP following REST.
• The components of RESTful web service APIs are the following:
• Base URI
• Internet media type (MIME) of data
• Operations set (GET, PUT, POST, DELETE)
• Hypertext driven (strictly)

Example API (clients)

• /clients/ with GET lists clients, HEAD includes metadata.
• /clients/{id} with GET retrieves client data, HEAD includes metadata, PUT creates/modifies client with {id}, and DELETE removes client {id}.
• /clients/{id}/{addrid} with GET retrieves address data, HEAD includes address metadata, PUT modifies address, and DELETE removes address from client {id}.
• /clients/{id}/orders/ with GET lists orders and HEAD includes order list metadata.
• /clients/{id}/orders/{orderid} with GET returns order data, HEAD returns metadata, PUT modifies, and DELETE removes the order.

Multiple Representation of Responses

• Same API endpoint is accessible via different requests with the same parameters.
• Different representations are returned.
  • Example: http://search.twitter.com/search.atom?q=carlesm&count=5 returns ATOM XML
  • Example: http://search.twitter.com/search.json?q=carlesm&count=5 returns JSON

Finer Points of REST

• Maps well with CRUD:
  • Create corresponds to INSERT and POST
  • Read corresponds to SELECT and GET
  • Update corresponds to UPDATE and PUT
  • Delete corresponds to DELETE
• Used in "enterprise" database applications.
• It is easy to understand/test/debug.
• Can be used non-programatically by using: curl -i http://search.twitter.com/search.json?q=carlesm
• Specific API easy to create for many programming languages.
• Usable without specific API using: urllib2 (in python)

RESTful for Programmers

• Focuses on identifying nouns (resources) and finding the identifiers.
• Identify verbs (actions).
• Write sentences as: action + noun.
• For a "tapes" application: resources could be "bars" and "tapes".
• Plurals improves URL readability.
• Other resources include "users".

Choosing Verbs

• Use GET, POST, DELETE, PUT, or PATCH.
• Support POST (X-HTTP-Method-Override).
• Avoid GET/POST abuse.

Making Sentences

Action | HTTP Verb | Where/what?

• -- | --- | --- Get | GET | List (bar, tapas), Individual Create | POST | List -> add individual Update | PATCH / PUT | Individual (bar, tapa) Delete | DELETE | Individual (bar, tapa)

PUT vs. PATCH

• PUT replaces the entire resource.
• PATCH is a partial resource replacement.
• PUT sends all resource data, while PATCH sends only the differential transmission.
• PATCH is supported by many servers/frameworks/browsers.
• It supports Fallback (X-HTTP-Method-Override).
• Must design to work with cache/proxying devices.
• Transmission costs must be reduced.

Last-Modified

• Date of last modification with second precision.
• Example: Fri, 21 Dec 2012 21:12:13 UTC
• Requests with If-Modified-Since should only transmit if modified.

ETags

• Not specified in the standard.
• ID of resource version.
• Opaque (created/used by server).
• Usually a Hash (MD5, SHA1, etc.) of resource version, date, etc.
• Example Etag: 9f7a47cdffbd83b49ab23983401
• Requests with If-None-Match should only send if not matching.

Client Concurrency

• Multiple clients can update/create concurrently.
• This can be avoided with If-Unmodified-Since (date) or If-Match.
• This check if "actual" version is still the valid one.

Example API

• GET /bars/ returns a list of bars.
• GET /bars/ returns data of a single bar.
• POST /bars/ creates a new bar.
• PUT /bars/ modifies a bar.
• DELETE /bars/ deletes a bar.

HATEOAS (Hypermedia as the Engine of Application State)

• Each response should include links.
• Too many links can increase network usage chattiness.
• Solutions include summary data.
• A balance between data and links must be found.

HATEOAS Recommendations

• For each POST (create) include Links with the Location header of the created resource.
• For Collections (GET), each representation should include "self" link.
• Collections (GET) can include pagination links.
• Use ATOM link style: rel and href.
• rel can be: alternate, related, self, enclosure and via.
• rel can also be pagination: first, last, next, previous.
• Example of resource creation:

POST http://my.api.com/bars

HTTP/1.1 200 OK Status: 200 Connection: close Content-Type: application/json; charset=utf-8 Location: http//my.api.com/bars/1111

HATEOAS Code Example

{ 
  "data":[
    {"bar_id":"42", "name":"Lo Bar", "links":{"rel":"self","href":"http://my.api.com/bars/42"}},
    {"bar_id":"11","name":"Frankfurt","links":[{"rel":"self","href":"http://my.api.com/bars/11"}]},
    {"bar_id":"22", "name": "Cafe","links":[{"rel":"self","href":"http://my.api.com/bars/22"}]}
  ]
}