Representational State Transfer (REST) and HATEOAS
84
Representational State Transfer (REST) and HATEOAS Service-Oriented Architecture Computing + Mathematical Sciences Auckland University of Technology Image used under Creative Commons from apasciuto http://flickr.com/apasciuto/
-
Upload
xemacs-slartibartfast -
Category
Technology
-
view
7.521 -
download
3
description
Lecture from Auckland University of Technology in the Service-Oriented Architecture for the Master's course in Service-Oriented Computing (semester 2, 2013)
Transcript of Representational State Transfer (REST) and HATEOAS
Representational State Transfer (REST)and HATEOAS
Service-Oriented Architecture
Computing + Mathematical SciencesAuckland University of Technology
Image used under Creative Commons from apasciuto http://flickr.com/apasciuto/
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Outline
1 REST APIsIdentification of ResourcesManipulation of ResourcesSelf-Descriptive MessagesHATEOAS
2 Example Scenario
3 Pitfalls of REST Design
4 More Leveraging HTTPHTTP Status CodesETags & Optimistic Locking
5 REST Examples
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 2/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Outline
1 REST APIsIdentification of ResourcesManipulation of ResourcesSelf-Descriptive MessagesHATEOAS
2 Example Scenario
3 Pitfalls of REST Design
4 More Leveraging HTTPHTTP Status CodesETags & Optimistic Locking
5 REST Examples
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 3/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Warning before we start!
REST != MVCDo not think in controllers, IDs, actions, models,views, plugins, helpers . . .In fact, do not think about implementation at all!
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 4/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
What is REST?Roy Fielding, “Father” of REST
REST is a coordinated set of architecturalconstraints that attempts to minimize latency andnetwork communication while at the same timemaximizing the independence and scalability ofcomponent implementations. This is achieved byplacing constraints on connector semantics whereother styles have focused on component semantics.REST enables the caching and reuse ofinteractions, dynamic substitutability ofcomponents, and processing of actions byintermediaries, thereby meeting the needs of anInternet-scale distributed hypermedia system.
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 5/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
What is REST?
8 REST is not a standard8 REST is not a protocol
REST is an architectural style for networked applicationsREST defines a set of simple principles(loosely followed by most API implementations)
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 6/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
What is REST?Advantages of REST
CacheableStatelessScalableFault-tolerantLoosely coupled
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 7/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
What is REST?Principles of REST
URL identifies a resourceURLs have a hierarchyMethods perform operations on resourcesOperation must be implicitHypermedia format to represent dataLink relations to navigate
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 8/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
What is REST?The Four Main Principles
1 Identification of resources2 Manipulation of resources3 Self-descriptive messages4 HATEOAS
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 9/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Identification of ResourcesYou are doing it wrong . . . :-(
/index.php?action=getarticle&id=5
/default/article/5/4/6/size
Cacheable? Scalable? Readable?
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 10/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Identification of ResourcesReadable and Maintainable!
/articles
We want all articles/articles/5/photos/4/comments/1
We want the first comment of the fourth photofor the fifth article/articles/5/photos/4/comments
We want all comments of the fourth photofor the fifth article
Cacheable! 4 Scalable! 4 Readable! 4
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 11/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Identification of ResourcesFiltering through a Query String, not the URI
8 /photos/order/size/limit/5
8 /photos/limit/5/order/size
4 /photos?order=size&limit=5
4 /photos?limit=5&order=size
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 12/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Manipulation of Resources
CreateRetrieveUpdateDelete
But please note: REST != CRUD
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 13/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Manipulation of ResourcesCRUD to HTTP verb mapping
Create = POST
Retrieve = GET
Update = PUT (or PATCH)Delete = DELETE
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 15/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Manipulation of ResourcesCreating a Resource
POST creates a new resourceBut the server decides on that resources URIExamples
WWW: Posting to Web log→ Server decides URI of posting
and any comments made on that post
Programmatic service: Creating a new employee record
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 16/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Manipulation of ResourcesSafe Methods
Any client should be able to make the request. . . as many times as necessaryGET, OPTIONS, HEAD
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 17/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Manipulation of ResourcesIdempotent Methods
Guarantees that the client can repeat the requestwhen it’s not certainx++ vs. x=4All methods except “POST”
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 18/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Self-Descriptive Messages
Stateless!All information for processing is available:
How? (method + content-type)What? (URI)When? (preconditions)Who? (authentication)
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 19/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Self-Descriptive MessagesHow: Method
GET /article/1234 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonAuthorization: OAuth oauth_nonce="123" ...If-None-Matched: absad12412414
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 20/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Self-Descriptive MessagesHow: Content-Type
GET /article/1234 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonAuthorization: OAuth oauth_nonce="123" ...If-None-Matched: absad12412414
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 21/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Self-Descriptive MessagesHow: Content-Type
application/vnd.mycompany.myapp-v1+json???The vnd name space is for proprietary media types(as opposed to the IANA registered ones)We want to “talk” JSON, not XML or othersWe wnat to “play” with API version 1.0 (not any other)General notes:
Interpret requests generouslyBe strict with responses
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 22/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Self-Descriptive MessagesWhat
GET /article/1234 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonAuthorization: OAuth oauth_nonce="123" ...If-None-Matched: absad12412414
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 23/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Self-Descriptive MessagesWhen
GET /article/1234 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonAuthorization: OAuth oauth_nonce="123" ...If-None-Matched: absad12412414
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 24/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Self-Descriptive MessagesWho
GET /article/1234 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonAuthorization: OAuth oauth_nonce="123" ...If-None-Matched: absad12412414
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 25/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Self-Descriptive Messages?Encoding
Google Trends chart: “XML API vs JSON API”(http://ur1.ca/ey5o6)
JSON feels more self-descriptive, too . . .
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 26/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Self-Descriptive MessagesWADL?
We can describe RESTful XML Web Services(similar to WSDL)Web Application Description Language (WADL)(another XML grammar to describe HTTP-based webapplications)But we don’t need a static contract description
→ We want self-descriptive messages, dammit!
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 27/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
HATEOASHATEOAS to the rescue!
HATEOAS=
Hypermedia As The Engine Of Application State
→ Magic awesome sauce to improve REST!
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 28/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
HATEOAS
This is the hardest and of course,most important part of REST
. . . But it makes the API “explorable”!
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 29/84
Image used under Creative Commons from oliverkendal http://flickr.com/oliverkendal/
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Links
Use links to allow clients todiscover locations and operationsLink relations are used to express optionsClients do not need to know URLsThis controls the state
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 31/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Links
Links contain (adapted from Atom format’s link definition):The target (href, mandatory)A short relationship indication (rel, mandatory)(e. g. “details”, “payment”, “cancel”)The content type needed for the request (type, optional)The HTTP method (method, optional)See also:http://www.subbu.org/blog/2008/10/generalized-linking
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 32/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Outline
1 REST APIsIdentification of ResourcesManipulation of ResourcesSelf-Descriptive MessagesHATEOAS
2 Example Scenario
3 Pitfalls of REST Design
4 More Leveraging HTTPHTTP Status CodesETags & Optimistic Locking
5 REST Examples
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 33/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Flight Booking APIState inside your REST API
The HATEOAS links indicate state transitions
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 34/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Search for Specified Flights
POST /search?order=price&limit=5 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+json
{ "destination": "LAX","date": "2013-09-24","type": "firstclass"
}
Note:This is an operation on a non-CRUD controller resource
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 35/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Returns a Collection of Flights
HTTP/1.1 200 OKContent-type: application/vnd.mycompany.myapp-v1.0+json
{ "flights": [{ "flightno": "NZ1234", "time": "4:20","links": [{ "href": "/flight/15263", "method": "GET","rel": "details", "type": "application/vnd.mycompany.myapp+json" },
{ "href": "/booking", "method": "POST","rel": "confirm", "type": "application/vnd.mycompany.myapp+json" },
]},{ "flightno": "EH123", "time": "3:55","links": [{ "href": "/flight/523525, "method": "GET","rel": "details", "type": "application/vnd.mycompany.myapp+json" },
{ "href": "/booking", "method": "POST","rel": "confirm", "type": "application/vnd.mycompany.myapp+json" },
]}]
}
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 36/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Returns a Collection of Flights
HTTP/1.1 200 OKContent-type: application/vnd.mycompany.myapp-v1.0+json
{ "flights": [{ "flightno": "NZ1234", "time": "4:20","links": [{ "href": "/flight/15263", "method": "GET","rel": "details", "type": "application/vnd.mycompany.myapp+json" },
{ "href": "/booking", "method": "POST","rel": "confirm", "type": "application/vnd.mycompany.myapp+json" },
]},{ "flightno": "EH123", "time": "3:55","links": [{ "href": "/flight/523525, "method": "GET","rel": "details", "type": "application/vnd.mycompany.myapp+json" },
{ "href": "/booking", "method": "POST","rel": "confirm", "type": "application/vnd.mycompany.myapp+json" },
]}]
}
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 37/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Confirm a Specific Flight
POST /booking HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+json
{ "flight": "/flight/15263","seat": "42A","meal": "vegetarian"
}
HTTP/1.1 401 Authentication required
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 38/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Confirm a Specific Flight. . . with more info
POST /booking HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonAuthorization: OAuth ...
{ "flight": "/flight/15263","seat": "42A","meal": "vegetarian"
}
HTTP/1.1 201 CreatedLocation: /booking/1616163
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 39/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
What can we do with our booking?
OPTIONS /booking/1616163 HTTP/1.1Host: www.mycompany.co.nzAuthorization: OAuth ...
HTTP/1.1 200 OKAllow: GET, PUT, DELETE
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 40/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Cancel our booking!
DELETE /booking/1616163 HTTP/1.1Host: www.mycompany.co.nzAuthorization: OAuth ...
HTTP/1.1 204 No content
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 41/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Still need to Pay for the Flight
GET /booking/1616163 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonAuthorization: OAuth ...
HTTP/1.1 200 OKContent-type: application/vnd.mycompany.myapp-v1.0+json
{ "flight": {"flightno": "NZ1234", "time": "4:20","links": [{ "href": "/flight/15263", "method": "GET","rel": "details", "type": "application/vnd.mycompany.myapp+json" } ]
},"payment": {"status": "Not paid","links": [{ "href": "/payment/booking/1616163", "method": "GET","rel": "details", "type": "application/vnd.mycompany.myapp+json" },
{ "href": "/payment/booking", "method": "POST","rel": "pay", "type": "application/vnd.mycompany.myapp+json" },
{ "href": "/booking/1616163", "method": "DELETE","rel": "cancel", "type": "application/vnd.mycompany.myapp+json" },
]}
}
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 42/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Pay through another resource
POST /payment/booking HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonAuthorization: OAuth ...
{ "booking": "/booking/1616163","cardno": "4111-1111-1111-1111","expires": "04/2014","name": "Guy Kloss","amount": { "currency": "NZD",
"value": 1414.00 }}
HTTP/1.1 201 CreatedLocation: /payment/booking/54321
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 43/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Can’t delete booking (already paid)
OPTIONS /booking/1616163 HTTP/1.1Host: www.mycompany.co.nzAuthorization: OAuth ...
HTTP/1.1 200 OKAllow: GET
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 44/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
We can fetch our e-Ticket now
GET /booking/1616163 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonAuthorization: OAuth ...
HTTP/1.1 200 OKContent-type: application/vnd.mycompany.myapp-v1.0+json
{ "flight": {"flightno": "NZ1234","time": "4:20","links": [ { "href": "/flight/15263", "method": "GET","rel": "details", "type": "application/vnd.mycompany.myapp+json" } ]
},"payment": {"status": "Paid in full""links": [ { "href": "/payment/booking/54321", "method": "GET","rel": "details", "type": "application/vnd.mycompany.myapp+json" } ]
},"links": [ { "href": "/eticket/12415156261616", "method": "GET","rel": "eticket", "type": "application/pdf" } ]
}
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 45/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Outline
1 REST APIsIdentification of ResourcesManipulation of ResourcesSelf-Descriptive MessagesHATEOAS
2 Example Scenario
3 Pitfalls of REST Design
4 More Leveraging HTTPHTTP Status CodesETags & Optimistic Locking
5 REST Examples
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 46/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
(Common) Pitfalls of REST Design
VersioningMethods in URIOne URI per resourceController resources & non-CRUD
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 47/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Versioning
8 /api/v1.1/article/1234/photos
8 /api/v1.2/article/1234/photos
Different resources?
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 48/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Versioning
OK:GET /api/article/1234/photos HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp+json ; version = 1.0
4 Better:GET /api/article/1234/photos HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+json
GET /api/article/1234/photos HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1.1+json
GET /api/article/1234/photos HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v5.0.4a+json
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 49/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Versioning
Why? It doesn’t break the resource’s URI→ Same resource→ Easier to evolve!
See also:http://barelyenough.org/blog/2008/05/versioning-rest-web-services/
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 50/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Methods in URI
/api/get/articles/1234/photos
/api/articles/new
/api/articles/list
Don’t use verbs in REST URIs!
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 51/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
One URI per Resource
/api/article/1234
/api/article/red+teddybear
Different resources!?!
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 52/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
One URI per Resource
If you must . . .
GET /api/article/red+teddybear HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+json
HTTP/1.1 302 FoundLocation: /api/article/1234
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 53/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Controller Resources & Non-CRUD
Outside the CRUD?Multiple operations simultaneously?
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 54/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Controller Resources & Non-CRUDPOST /distance HTTP/1.1Host: www.mycompany.co.nzAccept: application/jsonContent-type: application/json;charset=UTF-8
{ "from": "Auckland, NZL","to": "Hamilton, NZL"
}
or:
GET /distance?from=...&to=... HTTP/1.1Host: www.mycompany.co.nzAccept: application/json
HTTP/1.1 200 OKContent-length: 123Content-type: application/json
{ "km": 127.5,"miles": 78.9
}
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 55/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Controller Resources & Non-CRUD
POST /user/gkloss/address_merge HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonContent-type: application/csv;charset=UTF-8
John Doe, 1 Main Street, Seattle, WAJane Doe, 100 North Street, Los Angeles, CA
HTTP/1.1 303 See otherLocation: /user/gkloss/addressbook
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 56/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Outline
1 REST APIsIdentification of ResourcesManipulation of ResourcesSelf-Descriptive MessagesHATEOAS
2 Example Scenario
3 Pitfalls of REST Design
4 More Leveraging HTTPHTTP Status CodesETags & Optimistic Locking
5 REST Examples
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 57/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
More Important Stuff
HTTP Status codesETags
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 58/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
HTTP Status Codes
Status codes are importantThey represent the result of your actions
See: http://en.wikipedia.org/wiki/Http_status_codes
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 59/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
HTTP Status Codes
1xx → Informational2xx → Success3xx → Redirection4xx → Client error5xx → Server error
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 60/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
HTTP Status CodesImportant 2xx Codes
200 OK→ Resource returned201 Created→ Resource created204 No content→ Resource deleted
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 61/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
HTTP Status CodesImportant 3xx Codes
301 Moved Permanently→ Resource reorganised302 Found→ Redirection for specific object (e. g. search)303 Other→ A redirect due to an operation304 Not modified→ Resource wasn’t changed
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 62/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
HTTP Status CodesImportant 4xx Codes
400 Bad request→ Incorrect payload401 Unauthorized→ Not authorized to operate403 Forbidden→ Not authorized to operate404 Not found→ Resource was not found405 Method not allowed→ Method incorrect406 Not acceptable→ Cannot return in correct format412 Precondition failed→ “ETag mismatch”(418 I’m a teapot→ Hyper Text Coffee Pot Control Protocol)
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 63/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
HTTP Status Codes
501 Not implemented vs. 405 Method not allowed409 Conflict vs. 412 Precondition failed
→ de·bat·a·ble/di’batUbUl/Adjective
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 64/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Useful HTTP Headers
If-Unmodified-Since
(problem: only 1 second granularity)If-Match and If-None-Match
(used with ETag value)Remember: State can change in the meantime
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 65/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
ETags & Optimistic Locking
GET /blogpost/12345 HTTP/1.1Host: www.mycompany.co.nz
HTTP/1.1 200 OKContent-length: 12340Content-type: application/jsonETag: abcd-1234
{ "author": "Guy Kloss","title": "Frobnification of Sub-Marine Vehicles",...
}
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 66/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
ETags & Optimistic LockingFor Caching
GET /blogpost/12345 HTTP/1.1Host: www.mycompany.co.nzIf-None-Match: abcd-1234
HTTP/1.1 304 Not modified
→ Blog post is cached and can be used
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 67/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
ETags & Optimistic LockingFor Concurrency Protection
PATCH /blogpost/12345 HTTP/1.1Host: www.mycompany.co.nzIf-Match: abcd-1234
{ "author": "Heinrich von Zinkeduetten" }
HTTP/1.1 412 Precondition failed
Blog post was concurrently modified by “someone”HTTP PATCH performs a partial update
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 68/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Outline
1 REST APIsIdentification of ResourcesManipulation of ResourcesSelf-Descriptive MessagesHATEOAS
2 Example Scenario
3 Pitfalls of REST Design
4 More Leveraging HTTPHTTP Status CodesETags & Optimistic Locking
5 REST Examples
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 69/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
An XML ExampleJust to show you, it does work with XML, too.
PUT /booking/1616163 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+xmlAuthorization: OAuth ...
<booking><flight>/flight/15263</flight><seat>17F</seat><meal>halal</meal>
</booking>
HTTP/1.1 200 OKConent-type: application/vnd.mycompany.myapp-v1.0+xml
<booking><link rel="details" href="/booking/1616163"
method="GET" type="application/vnd.mycompany.myapp+xml"><link rel="payment" href="/payment/booking"
method="POST" type="application/vnd.mycompany.myapp+xml"><link rel="cancel" href="/booking/1616163"
method="DELETE" type="application/vnd.mycompany.myapp+xml"></booking>
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 70/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Creating a Resource
POST /articles HTTP/1.1Host: www.mycompany.co.nzContent-type: application/vnd.mycompany.myapp-v1+json
{ "name": "Teddybear","colour": "red","stock": 15,"price": { "EUR": 15.95,
"NZD": 26.95 }}
HTTP/1.1 201 CreatedLocation: /articles/1234
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 71/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Getting a Resource Collection
GET /articles HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+json
HTTP/1.1 200 OKContent-length: 12345Content-type: application/vnd.mycompany.myapp-v1.0+jsonDate: sun, 08 Aug 2013 12:34:56 NZST
{ "articles": [{ "name": "Rubic’s Cube","links": [ { "href": "/articles/1233", "method": "GET",
"rel": "article", "type": "application/vnd.mycompany.myapp+json" } ]},{ "name": "Teddybear","links": [ { "href": "/articles/1234", "method": "GET",
"rel": "article", "type": "application/vnd.mycompany.myapp+json" } ]}]
}
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 72/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Getting a Resource
GET /articles/1234 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+json
HTTP/1.1 200 OKContent-length: 12345Content-type: application/vnd.mycompany.myapp-v1.0+jsonETag: 23709-12135125Date: sun, 08 Aug 2013 12:34:56 NZST
{ "name": "Teddybear","manufacturer": "Steiff","colour": "red","stock": 30,...
}
HTTP/1.1 404 Not foundContent-length: 0Date: sun, 08 Aug 2013 12:34:56 NZST
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 73/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Deleting a Resource
DELETE /articles/1234 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+json
HTTP/1.1 204 No contentContent-length: 0Date: sun, 08 Aug 2013 12:34:56 NZST
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 74/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Updating a Resource
PUT /articles/1234 HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonIf-Match: 23709-12135125
{ "name": "Teddybear","manufacturer": "Steiff","colour": "red","stock": 30,"price": { "EUR": 15.95,
"NZD": 26.95 }}
HTTP/1.1 200 OKContent-length: 0Date: sun, 08 Aug 2013 12:34:56 NZST
HTTP/1.1 412 Precondition failedContent-length: 0Date: sun, 08 Aug 2013 12:34:56 NZST
Idempotent!Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 75/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Updating a Resource
PUT is an idempotent operationIt (completely) replaces the contentof the whole resourceConsider PATCH for partial updates!
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 76/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Controller Resources (Non-CRUD)Revisited . . .
POST /user/gkloss/address_merge HTTP/1.1Host: www.mycompany.co.nzAccept: application/vnd.mycompany.myapp-v1+jsonContent-type: application/csv;charset=UTF-8
John Doe, 1 Main Street, Seattle, WAJane Doe, 100 North Street, Los Angeles, CA
HTTP/1.1 303 See OtherLocation: /user/gkloss/addressbook
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 77/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Conclusion
Web-based services are about state machinesand business protocols→ The HATEOAS constraint from REST
What can be called “RESTful” depends on who you ask(it’s not a formally accepted definition)
Some say: You are not RESTful without hypermediaI say: REST is about Representational State Transfer,and hypermedia is an add-on (though very important)
4 There are still good APIs without hypermedia(e. g. Amazon S3)
8 There are very bad APIs (pretending to be RESTful)(e. g. Twitter API)
If in doubt, certain APIs can be considered “RESTish”Certain ones are definitely no more than RESTish!
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 78/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Comparison REST vs. SOAP
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 79/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Comparison REST vs. SOAP
Both are request/response type servicesSOAP is more an RPC-style API (procedures with verb)REST is about REST (duh!)SOAP has strictly defined interfaces,and the communication can be verifiedREST is more about evolving APIs,and making them explorable through hypermediaBells’n’whistles in SOAP, but can be found in REST(less obvious, less used: WADL, JSON schema, . . . )Use . . .
SOAP for well managed “corporate-style” consumersREST for many, less-defined “citizen consumers”REST if the API is likely to evolve
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 80/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
More Reading
Wikipedia: Representational State Transferhttp://en.wikipedia.org/wiki/Representational_State_Transfer
Roy Fielding’s PhD dissertation coming up with the REST idea:http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
“RESTful Web Services Cookbook –Solutions for Improving Scalability and Simplicity”http://oreilly.com/catalog/9780596801694
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 81/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
More ReadingOnline Slide Presentations
“Designing HTTP Interfaces and RESTful Web Services”http://www.slideshare.net/Wombert/
designing-http-interfaces-and-restful-web-services-dpc2012-20120608
“HATEOAS: The Confusing Bit from REST”http://www.slideshare.net/adorepump/
hateoas-the-confusing-bit-from-rest
“REST in Practice”http://www.slideshare.net/guilhermecaelum/rest-in-practice
“RESTful Web APIs with Python, Flask and MongoDB”https://speakerdeck.com/nicola/
developing-restful-web-apis-with-python-flask-and-mongodb
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 82/84
������������ �������
�������������������
���������� !�"#�$%�#��&'()���*��'�)+�'(��&��#(''",--�./"&0)�/)#1-
�%�%��&�)��������%��
2��(�����'��304����
��%*�#!%'&�)+
��0(�)�)1& !����
5�%#���3�����*�!
63%��%�157���!)
4�)����!�23%��%�1
5�85��'���� !�0%'&
0�$"3!/
�����96��
:;<
�������
��9� �������
� �=�6� ���
6�����
Questions? Image used under Creative Commons from Boston Public Libraryhttp://flickr.com/boston_public_library/
