1

REST - Introduction

• Based on material from InfoQ.com (Stefan Tilkov)• And slides from MindTouch.com (Steve Bjorg)

2

Key REST principles

• REST is a set of principles that define how Web standards, such as HTTP and URIs, are supposed to be used

• The principles:‒ Give every “thing” an ID‒ Link things together‒ Use standard methods‒ Resources with multiple representations‒ Communicate statelessly

3

Give every “thing” an ID

• Everything that should be identifiable should obviously get an ID• On the Web, there is a unified concept for IDs: The URI. • URIs make up a global namespace, and using URIs to identify your

key resources means they get a unique, global ID.• It is not a pre-requisite in REST to construct human readable URIs,

but it makes it easier to use.• Use URIs to identify everything that merits being identifiable,

specifically, all of the “high-level” resources that your application provides, whether they represent individual items, collections of items, virtual and physical objects, or computation results.

4

Give every “thing” an ID

• What is the difference betweens the URIs in the first box compared to the second box?

http://example.com/customers/1234http://example.com/orders/2007/10/776654http://example.com/products/4554http://example.com/processes/salary-increase-234

http://example.com/orders/2007/11http://example.com/products?color=green

5

Link things together

• “Hypermedia as the engine of application state”, HATEOAS• Hypermedia: the idea of links – as in HTML

<order self='http://example.com/customers/1234' > <amount>23</amount> <product ref='http://example.com/products/4554' /> <customer ref='http://example.com/customers/1234' /></order>

• An application can get information about product and customer by following the links

• Use links to refer to identifiable things (resources) wherever possible.

6

Use standard methods

• The standard methods (verbs) of HTTP are:‒ GET (request a resource)‒ POST (usually create new resource)‒ PUT (update or create ressource)‒ DELETE (delete ressource)‒ HEAD and OPTIONS

• Using HTTP ensures that the opponent knows what you mean.• Also the HTTP methods, except POST, are idempotent, so you may

call a method, e.g. GET, again if you don’t receive a response• RESTful services must obey the restrictions of HTTP• But is that really a problem?

See next slide

7

Example

• Traditional service interfaces:• The services and operations are connected to a specific resource• Therefore the client must have specific knowledge of the

interface/ application protocol

8

Example (procurement)RESTful• In a RESTful HTTP approach, you would have to get by with the

generic interface that makes up the HTTP application protocol.• The specific operations of the service are mapped to the standard

HTTP methods• E.g. A GET on a URI that identifies a customer is just as

meaningful as a getCustomerDetails operation

9

Compare traditional services and RESTful services

• The triangle: Pick any two• In traditional services you might have many operations, many data

types but few instances (Services, remote objects, endpoints etc.)• In RESTful services you have a limited number operations (4),

many data types and many instances (could be any thing on the web, i.e. http servers, gateways, providers like Google, Yahoo, Live, etc.)

• Recap: For clients to be able to interact with your resources, they should implement the default application protocol (HTTP) correctly, i.e. make use of the standard methods GET, PUT, POST, DELETE.

10

Resources with multiple representations

• How does a client know how to deal with the data it retrieves, e.g. as a result of a GET or POST request?

• The approach taken by HTTP, is to allow for a separation of concerns between handling the data and invoking operations.

• In other words, a client that knows how to handle a particular data format can interact with all resources that can provide a representation in this format.

How does this differ from OOP?

11

Resources with multiple representations

• Using HTTP content negotiation, a client can ask for a representation in a particular format:

GET /customers/1234 HTTP/1.1Host: example.com Accept: application/vnd.mycompany.customer+xml

GET /customers/1234 HTTP/1.1Host: example.com Accept: text/x-vcard

You can also do it explicit in the URI, e.g. /customers/1234?vcard or /customers/1234/vcard

12

Resources with multiple representations

• Ideally, the representations of a resource should be in standard formats ‒ If a client “knows” both the HTTP application protocol and a

set of data formats, it can interact with any RESTful HTTP application in the world in a very meaningful way.

‒ Unfortunately, we don’t have standard formats for everything, but you can create some for your own ecosystem.

• Of course all of this does not only apply to the data sent from the server to the client, but also for the reverse direction ‒ A server that can consume data in specific formats does not

care about the particular type of client, provided it follows the application protocol.

13

Resources with multiple representations

• If you provide both xml and html, you can turn your application’s Web UI into its Web API

• API design is often driven by the idea that everything that can be done via the UI should also be doable via the API.

GET /customers/1234 HTTP/1.1Host: example.com Accept: application/vnd.mycompany.customer+xml

GET /customers/1234 HTTP/1.1Host: example.com Accept: text/html

14

Communicate statelessly

• Most applications are not stateless• But the state should be kept in the client or in an resource• It means that the server should not maintain state for each client• One reason is that it makes the client independent of changes on

the server side, and even makes it possible to use another server if the first one crashes during a transaction.

• Another reason is scalability. It affect the servers performance if it must keep client state for a huge number of clients.

• Therefore it not RESTful to use the session object

REST by Example

Some slides from

from MindTouch.com

Problem Statement

Customer wants to update his order with ACME Enterprises

REST Example

<customer><name>Wile E. Coyote</name><portrait>http://coyote.com/my_portrait.png</portrait><orders>http://acme.com/customers/coyote/orders</orders>

</customer>

/customers/coyote

GET

Get the customer

REST Example

<orders><customer>http://acme.com/customers/coyote</customer><next>http://acme.com/customers/coyote/orders?before=11</next><order id="20">

<uri>http://acme.com/orders/1234</uri><status>open</status>

</order>...

</orders>

/customers/coyote /customers/coyote/orders

GET

GET

Get a list of customer’s orders

REST Example

<order><customer>http://acme.com/customers/coyote</customer><status>open</status><item quantity="1">ACME Rocket</item>

</order>

/customers/coyote /customers/coyote/orders /orders/1234

GET

GET

GET

Get a specified order

REST Example

<order><customer>http://acme.com/customers/coyote</customer><status>open</status><item quantity="4">ACME Rocket</item>

</order>

/customers/coyote /customers/coyote/orders /orders/1234

GET

GET

GET

PUT

Change the specified order

REST Example

/customers/coyote /customers/coyote/orders /orders/1234

GET

Simple• resource-centric• few verbs

Scalable• resource discovery• stateless protocol

Layered• cacheable results• intelligent intermediaries

GET

GET

PUT