REST4DEV

Uniform interface

• Uniform identifiers for important resources
• Same access methods for resources
• Manipulate resources by exchanging representations
• Representations are self-descriptive messages
• Hypermedia as the engine of application state (HATEOAS)

Representational State Transfer

address

Problem domain

Solution

distributed hypermedia system

network-based application

Architectural Style

Software architecture = {Elements, Constraints, Rationale}

style : architecture

Consequences

patten : design

bring

Elements: data, process, connector

Constraints: configuring and organizing elements

Rationale: reasons behind the decisions

Christopher Alexander. The Timeless Way of Building. Oxford University Press, New York, 1979.

Dewayne E. Perry and Alexander L. Wolf. Foundations for the study of software architecture. SIGSOFT Softw. Eng. Notes, 17(4):40--52, 1992.

Define a style

address

An introduction to REST

Problem domain

Common characteristics

of design problems

Solution

Element types and roles

Common constrains

Common Rationale

Dong Liu

FRIB, MSU

Consequences

bring

Structure

Behavior

Implementation

Representational State Transfer

Architectural style

CORBA

RMI

Firewall

XML-RPC

RPC

SOAP

WS-*

Richardson Maturity Model

3

2

1

REST

0

"REST" vs RPC/SOAP

http://martinfowler.com/articles/richardsonMaturityModel.html

Case study

Scenario

• A web application for cable management
• Request/approval/procurement/installation workflow

Paradigm

World Wide Web

Design-by-buzzword is a common occurrence. At least some of this behavior within the software industry is due to a lack of understanding of why a given set of architectural constraints is useful.

• Test driven development
• Refactoring

Roy Fielding

Architectural Styles and the Design

of Network-based Software Architectures

RESTful

R. Fielding

Resources

Cables

Requests

Cables

Application/test

Identifiers

to slash or not to slash

GET /requests/

• Javascript
• API
• Other representations

HTTP

/requests/

/requests/:id

How about others?

Content negotiation was not considered practical

/requests

/request

/cablerequest

/requests/:id

How about json?

• Traditionally, slash represents the directory hierarchy in a file system
• Similarly, url/ implies a collection of resources, and url implies an entity
• When a full URL is derived from a relative URL, whether the base URL is ended with a slash is critical, see http://www.w3.org/TR/WD-html40-970708/htmlweb.html#relative-urls
• If you want to forward the clients to the right URL if they add or miss slash, try a tool like https://github.com/ericf/express-slash

Methods

• GET: retrieve the request
• PUT: update the request
• Delete

GET /requests/

Accept: application/json

Representations

GET /reqeusts/json

Application/test

GET /reqeusts.json

HTTP content negotiation was one of those "nice in theory" protocol additions that, in practice, didn't work out.

...

Many people seem to use HTTP content negotiation as a motivation for adding 'version' parameters to MIME types or registering new MIME types, with the hopes that the MIME types or parameters would be useful in HTTP content negotiation, and we should warn them that it isn't really productive to do so. That's why it might be useful advice to add to the guidelines for registering MIME types, should those ever be updated.

See http://www.alvestrand.no/pipermail/ietf-types/2006-April/001707.html

Round 1

It is also not clear how the agent-driven content negotiation will work with caching

Representations

Methods

GET /requests/

Request:

Accept: text/html, ...

/requests/

GET

POST

the list of requests

Create a new request

!==

• POST
• GET
• PUT
• DELETE

• Create
• Retrieve
• Update
• Delete

Response:

200

request #1 link

request #2 link

...

more requests link

create a resource: POST or PUT

POST /resources/

representation of the new resource

201 Created

Location: http://host:port/reources/resource_id

202 Accepted

Check /resources/ later

PUT /resources/resource_id

representation of the new resource

201 Created

Location: http://host/reources/resource_id

409 Conflict

/reources/resource_id was already there and cannot be modified

204 No Content

301 Moved Permanently

Location: http://host/reources/other_resource_id

Web constraints and practices

Is this RESTful

Test the resource with a popular browser

• Provide URIs as identifiers for resources
• Assign distinct URIs to distinct resources
• Reuse an existing URI scheme
• NOT ignore message metadata
• Provide representations of the identified resource consistently and predictably
• Provide ways to identify links to other resources, including to secondary resources (via fragment identifiers)

More Resources

More in HTTP specification RFC 2616

A proxy resource

A better solution

Not RESTful

• A resource whose representation is retrieved from third-party API
• A simple solution is

request({

url: 'http://third/party/service',

timeout: 30 * 1000,

...

}, function (err, response, resBody) {

if (err) {

return res.json(503, ...);

}

...

});

• Representation is not consistent with the host
• Meta information of the third-party API can conflict with the host
• Sensible meta information from the third-party API can leak
• The status codes from the third-party API will confuse the clients
• How about timeout?
• ...

app.get('/proxy/resource', function (req, res) {

request.get('http://third/party/service').pipe(res);

})

http://www.w3.org/TR/2004/REC-webarch-20041215/

• Fielding's thesis
• RESTful Web Services by Richardson and Ruby
• RESTful Web APIs by Richardson, Amundsen, and Ruby
• Restful Web Services Cookbook by Allamaraju
• Yahoo REST discuss group (not active recently)
• RESTful API languages
• HAL (http://stateless.co/hal_specification.html)
• JSON API (http://jsonapi.org/)