Pragmatic Rest

Colorado Software Summit: October 19 – 24, 2008 © Copyright 2008, Yahoo! Inc.

Pragmatic REST
Building RESTful Web APIs

Subbu Allamaraju
Yahoo! Inc || http://subbu.org

Subbu Allamaraju – Pragmatic REST


About
  Tech Yahoo!
 Developing standards, patterns and
practices for HTTP web APIs
  Past
 At BEA
  A “Convert”

Subbu Allamaraju — Pragmatic REST Slide 2


Disclaimer

All the opinions I express here are mine
and do not necessarily represent those
of my present or past employers.

Subbu Allamaraju — Pragmatic REST 3


Agenda

REST – The Architecture

REST vs WS – Pros and Cons

Building HTTP APIs RESTfully



Smell Test

“We offer SOAP and REST end points”

“Our technology supports REST-style URLs”

“REST is not fit for machine-machine
interactions”



QUIZ



Are these RESTful?
http://example.org/persons?start=10&count=100
http://example.org/person/123.xml
http://example.org/person/123/address/4
http://example.org/movie/Gone_With_the_Wind
http://example.org/movie/Terminator/reviews



Is this RESTful?
GET /services/rest/?
method=flickr.photos.setPerms&photo_id=2691065403&
is_public=1&is_friend=0&is_family=0&perm_comment=1&
perm_addmeta=1 HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8

<rsp stat=quot;okquot;>
<photoid>2691065403</photoid>
</rsp>



Is this RESTful?
POST /services/rest/?
method=flickr.photos.getRecent&api_key=… HTTP/1.1
Host: example.org

HTTP/1.1 200 OK

<photos page=quot;1quot; pages=quot;10quot; perpage=quot;100”>
<photo id=quot;2947640330quot; owner=quot;15150729@N07”
secret=quot;…quot; server=quot;3060quot; farm=quot;4quot; title=quot;…quot;
ispublic=quot;1quot; isfriend=quot;0quot; isfamily=quot;0quot; />
…
</photos>
</rsp>



Is this RESTful?
GET /photos?filterBy=recent HTTP/1.1
Host: example.org

HTTP/1.1 200 OK

<photos page=quot;1quot; pages=quot;10quot; perpage=quot;100
total=quot;1000”>
…

</photos>
</rsp>



Is this RESTful?
GET /photos?filterBy=recent&api_key=blah
Host: example.org

200 OK

<rsp stat=”failquot;>
<err code=quot;96quot; msg=quot;Invalid signaturequot;/>
</rsp>



REST



REST is defined by four interface constraints:
identification of resources; manipulation of
resources through representations; self-
descriptive messages; hypermedia as the engine of
application state.
- Roy Fielding, 2000



In other words
1.  Resources and URIs
2.  Representations
3.  Uniform interface
4.  HATEOAS



But no
  Schemas
  Description languages
  Code generation
  Registries



REST/HTTP EXPLAINED



Tenet 1: Resources
  A thing with an identity
 A blog entry, a person, a friend, an address
  Resources are named via URIs
 http://example.org/blog/what-is-rest
 http://example.org/person/subbu
 http://example.org/person/subbu/friends
 http://example.org/person/subbu/address/home
  URIs are stable
 URIs are names
 Names don’t change often

17

Subbu Allamaraju — Pragmatic REST


Identifying Resources
  We will come back to this later

18



Assigning URIs
Think primary keys

A person http://example.org/person/123
An address of a http://example.org/person/123/address/4
person
A movie http://example.org/movie/Gone_With_the_Wind
Reviews of a http://example.org/movie/Terminator/reviews
movie
A group of http://example.org/persons?start=10&count=100
people



URIS are Generally Opaque
Clean URIs don’t generally matter

http://example.org/76asfg2g

Okay as long as clients don’t have to
parse and understand these

URI Opacity - We will come back to this
later



URI Design Considerations
Opaque to client apps –
Transparent to client developers

Hierarchical path segments
A good way to organize resources

http://example.org/movie/Terminator/
reviews

21



URI Considerations
Reserve query params for optional inputs
(A convention, not a rule)

http://example.org/movies

findBy
{latest,director,studio}
fromYear
Year
toYear Year
location Postal code, or city
…

22



Tenet 2: Representations
Things sent over requests and received
over responses

An XML representation of a book

A PNG representation of a map

Data submitted through an HTML form to create a user

A JSON representation of the user created

An HTML view of the same user

23



Media Types
Like the “type” of an object
Like the “schema” of an XML element
An XML representation of a book: application/
vnd.example.book+xml

A PNG representation of a map: image/png

HTML form submission: application/x-www-form-urlencoded

A JSON representation of the user created: application/
vnd.example.user+json

An HTML view of the same user: text/html

24



Representations are Negotiable
Accept: application/atom+xml;q=1.0,text/html;q=0.1
Accept-Charset: UTF-8

Content-Type: application/atom+xml;charset=UTF-8

Accept-Language: fr;q=1.0,en=0.8

Content-Language: en

Accept-Encoding: gzip,deflate

Content-Encoding: deflate

25



Varying a Response
Don’t overload URIs
Tell intermediaries and clients how you
chose a representation
Accept: application/atom+xml;q=1.0,text/htm;q=0.1
Accept-Charset: UTF-8
Accept-Language: fr;q=1.0,en=0.8
Accept-Encoding: gzip,deflate

Content-Type: application/atom+xml;charset=UTF-8

Content-Encoding: deflate

Vary: Accept,Accept-Encoding



Tenet 3 – Uniform Interface
Network transparency
  A uniform interface to operate on
resources
  Uniform interface == A fixed set of
operations
  Uniform interface == Generic interface
 Irrespective of what resource is being
operated on

27



HTTP is a Uniform Interface
CRUD

A protocol between clients and resources

GET •  Get a representation
•  Safe and idempotent

POST •  Like a factory operation
•  Unsafe and non-idempotent

PUT •  Create or update a resource
•  Unsafe but idempotent

DELETE •  Delete a resource
•  Unsafe but idempotent



A Generic Application Protocol
  CRUD on resources
  Content negotiation
  Caching
  Optimistic concurrency

29



Is CRUD Crude?
  Yes, may be – depends on how you
identify resources

30



Domain Nouns
Obvious Approach
  Nouns in your application domain
  NYT Movie Reviews API
 Movies, Reviews, Critics, Critic’s picks,
Reviews by reviewer
  Netflix API
 Catalog, Users, Rentals, Rental History,
Rental Queue, Reviews, Recommendations
etc.



Composites
Listen to Client Developers

A map with traffic directions + weather
alerts + and construction data
A user profile with 5 contacts + favorite
colors + 10 latest updates

  A group of other resources
  Generally read-only



Tasks and Processes
Clear the CRUD

Transfer $100 from A to B
An order processing workflow
Hiring an employee

  Spawn several resources and have
their own lifecycle



Finding Resources

Domain Compo-
Nouns sites

Tasks &
Processes



HTTP Caching
GET /photo/2691065403/comments
200 OK
Last-Modified: Thu, 24 Jul 2008 16:25:14 GMT
ETag: 584219-2bb-80758e80
For DB stored data,
Cache-Control: max-age=300
maintain version IDs
and time stamps

GET /photo/2691065403/comments
If-Modified-Since: Thu, 24 Jul 2008 16:25:14 GMT

If-None-Match: 584219-2bb-80758e80

304 Not Modified



Optimistic Concurrency
GET /photo/2691065403/comment/1

200 OK
Last-Modified: Thu, 24 Jul 2008 16:25:14 GMT
ETag: 584219-2bb-80758e80
Cache-Control: max-age=300

PUT /photo/2691065403/comment/1
If-Unmodified-Since: Thu, 24 Jul 2008 16:25:14 GMT
If-Match: 584219-2bb-80758e80

412 Precondition Failed



Tenet 4: HATEOAS

“Hypermedia as the engine of application
state”



Web APIs without Hypermedia
POXy REST
  All URIs prepublished
  Clients solely rely on documentation
  Clients create URIs from scratch
  Representations are like POJOs



Hypermedia for Web APIs
<account>
<link href=quot;http://example.org/transaction/1quot;
rel=quot;self”/>
<link href=quot;http://example.org/account/1/historyquot;
rel=quot;http://example.org/rels/historyquot;/>
<link href=quot;http://example.org/customer/aZff13quot;
rel=quot;http://example.org/rels/customerquot;/>
…
</account>

http://tools.ietf.org/id/draft-nottingham-http-link-
header-02.txt for a consolidated list of well-known
relations.

Or define your own.



Hypermedia for Web APIs
Representations reflect app state
<customer>
<link href=quot;http://example.org/customer/aZff13quot;
rel=quot;self”/>
<link href=quot;http://example.org/invite?z09sa3kquot;
rel=quot;http://example.org/rels/verifyquot;/>
…
</profile>
e.g. a one time
link



HATEOAS – Consequences
  URIs are given to clients
 Or clients use known algorithms, or URI
templates
 Don’t have to prepublish all URIs
  URIs can be context and state sensitive
  URIs remain opaque
 Less coupling



URI Templates
Use when client needs to supply inputs

A URI to fetch all movies with title containing a
keyword:

http://example.org/movies?contains={keyword}



Describing Web APIs

Hypermedia and media types to reduce
the need for description languages
such as WADL

43



Describing Web APIs
No silver bullet

Publish a few root level URIs

OPTIONS to discover verbs

Media type specifications

Links with known relations to
discover new contextual URIs



EXAMPLE: ACCOUNT
TRANSFER



Account Transfer

A client app would like to transfer $100 from one
bank account to another.



Resources and URIs
Perhaps upon authentication or
through a previous search

Bank account: http://example.org/account/{id}

Transfers collection: http://example.org/transfers

Account transfer: http://example.org/transfer/{id}
Status: http://example.org/status/{…}
Prepublished, or linked
from an account
Link returned upon representation
account transfer

How do client apps find these URIs?



Representations

application/vnd.example.account+xml
application/vnd.example.transfer+xml
application/vnd.example.status+xml

Describe each media type



Link Relations

quot;selfquot;: To self-link to each resource
quot;editquot;: Link to create a new transfer request
quot;http://example.org/rels/sourcequot;: Source
quot;http://example.org/rels/targetquot;: Target
quot;http://example.org/rels/statusquot;: Status



Create a Transfer
POST /transfers HTTP/1.1
Host: example.org
Content-Type: application/vnd.example.transfer+xml

<transfer>
<link href=quot;http://example.org/account/1quot;
rel=quot;http://example.org/rels/sourcequot;/>
<link href=quot;http://example.org/account/2quot;
rel=quot;http://example.org/rels/targetquot;/>
<currency>USD</currency>
<amount>100.00</amount>
<note>Testing transfer</note>
</transfer>



Response
HTTP/1.1 201 Created
Location: http://example.org/transfer/1
Content-Type: application/vnd.example.transfer+xml

<transfer>
<link href=quot;http://example.org/transfer/1quot;
rel=quot;self”/>
<link href=quot;http://example.org/status/1?z09sa3kquot;
rel=quot;http://example.org/rels/statusquot;/>
<id>org:example:transfer:1</id>
…
</transfer>



Get Status
GET /status/1?z09sa3k HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
<status>
<link href=quot;http://example.org/status/1?z09sa3kquot;
rel=”selfquot;/>
<id>org:example:status:999</id>
<text>…</text>
</status>



QUIZ - REVISIT



Are these RESTful?
http://example.org/persons?start=10&count=100
http://example.org/person/123.xml
http://example.org/person/123/address/4
http://example.org/movie/Gone_With_the_Wind
http://example.org/movie/Terminator/reviews

There is nothing RESTful
or unRESTful.

These are just names of
resources.



Is this RESTful?
GET /services/rest/?
method=flickr.photos.setPerms&photo_id=2691065403&
is_public=1&is_friend=0&is_family=0&perm_comment=1&
perm_addmeta=1 HTTP/1.1
Host: example.org
Using an unsafe
operation over GET

HTTP/1.1 200 OK
Use PUT
Content-Type: text/xml; charset=utf-8

<photoid>2691065403</photoid>
</rsp>



Is this RESTful?
POST /services/rest/?
method=flickr.photos.getRecent&api_key=… HTTP/1.1
Host: example.org
Using GET and POST
synonymously
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
GET is idempotent and
not.
safe. POST is
<photos page=quot;1quot; pages=quot;10quot; perpage=quot;100”>
…
</photos>
</rsp>



Is this RESTful?
GET /photos?filterBy=recent HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Use links – not internal
Content-Type: application/xml;charset-UTF-8
IDs
<photos page=quot;1quot; pages=quot;10quot; perpage=quot;100
total=quot;1000”>
…

</photos>
</rsp>



Is this RESTful?
Hiding errors from
GET /photos?filterBy=recent&api_key=blah
intermediaries and
Host: example.org
client infrastructure.

Use 4xx or 5xx codes
200 OK

<rsp stat=”failquot;>
<err code=quot;96quot; msg=quot;Invalid signaturequot;/>
</rsp>



CHALLENGES



Key Challenges
  Modeling resources
 Not just as data, but linked and context
aware
  Respecting the uniform interface
  Programming to hypermedia

  And occasional fights between “that
one” and “the other one”.



THANKS


Pragmatic Rest

More Related Content

Pragmatic Rest