Guy K. Kloss, profile picture
Uploaded byGuy K. Kloss
PDF, PPTX12,970 views

Representational State Transfer (REST) and HATEOAS

This document outlines Representational State Transfer (REST) and HATEOAS (Hypermedia as the Engine of Application State). It discusses the principles of REST including identification of resources, manipulation of resources through HTTP methods, self-descriptive messages, and HATEOAS. An example scenario of a flight booking API is provided to illustrate how HATEOAS links indicate state transitions within a REST API.

Embed presentation

Download as PDF, PPTX
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/
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & 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 APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & 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 != MVC Do 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 architectural constraints that attempts to minimize latency and network communication while at the same time maximizing the independence and scalability of component implementations. This is achieved by placing constraints on connector semantics where other styles have focused on component semantics. REST enables the caching and reuse of interactions, dynamic substitutability of components, and processing of actions by intermediaries, thereby meeting the needs of an Internet-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? REST is not a standard REST is not a protocol REST is an architectural style for networked applications REST deļ¬nes 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 Cacheable Stateless Scalable Fault-tolerant Loosely 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 identiļ¬es a resource URLs have a hierarchy Methods perform operations on resources Operation must be implicit Hypermedia format to represent data Link 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 2 3 4 Identiļ¬cation of resources Manipulation of resources Self-descriptive messages 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 Identiļ¬cation of Resources You are doing it wrong . . . :-( /index.php?action=getarticleid=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 Identiļ¬cation of Resources Readable and Maintainable! /articles We want all articles /articles/5/photos/4/comments/1 We want the ļ¬rst comment of the fourth photo for the ļ¬fth article /articles/5/photos/4/comments We want all comments of the fourth photo for the ļ¬fth article Cacheable! Scalable! Readable! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 11/84
REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Identiļ¬cation of Resources Filtering through a Query String, not the URI /photos/order/size/limit/5 /photos?order=sizelimit=5 /photos/limit/5/order/size /photos?limit=5order=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 Create Retrieve Update Delete 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 Resources CRUD to HTTP verb mapping Create = POST Retrieve = GET Update = PUT (or Delete = DELETE PATCH) 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 Resources Creating a Resource creates a new resource But the server decides on that resources URI Examples POST 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 Resources Safe Methods Any client should be able to make the request . . . as many times as necessary GET, 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 Resources Idempotent Methods Guarantees that the client can repeat the request when itā€™s not certain x++ vs. x=4 All 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 Messages How: Method GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: 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 Messages How: Content-Type GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: 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 Messages How: 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 others We wnat to ā€œplayā€ with API version 1.0 (not any other) General notes: Interpret requests generously Be 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 Messages What GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: 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 Messages When GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: 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 Messages Who GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: 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 Messages WADL? We can describe RESTful XML Web Services (similar to WSDL) Web Application Description Language (WADL) (another XML grammar to describe HTTP-based web applications) 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 HATEOAS HATEOAS 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 to discover locations and operations Link relations are used to express options Clients do not need to know URLs This 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 deļ¬nition): 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 APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags 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 API State 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 Speciļ¬ed Flights POST /search?order=pricelimit=5 HTTP/1.1 Host: www.mycompany.co.nz Accept: 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 OK Content-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 OK Content-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 Conļ¬rm a Speciļ¬c Flight POST /booking HTTP/1.1 Host: www.mycompany.co.nz Accept: 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 Conļ¬rm a Speciļ¬c Flight . . . with more info POST /booking HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... { flight: /flight/15263, seat: 42A, meal: vegetarian } HTTP/1.1 201 Created Location: /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.1 Host: www.mycompany.co.nz Authorization: OAuth ... HTTP/1.1 200 OK Allow: 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.1 Host: www.mycompany.co.nz Authorization: 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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... HTTP/1.1 200 OK Content-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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: 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 Created Location: /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.1 Host: www.mycompany.co.nz Authorization: OAuth ... HTTP/1.1 200 OK Allow: 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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... HTTP/1.1 200 OK Content-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 APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags 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 Versioning Methods in URI One URI per resource Controller 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 /api/v1.1/article/1234/photos /api/v1.2/article/1234/photos Diļ¬€erent 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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp+json ; version = 1.0 Better: GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1.1+json GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: 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 Diļ¬€erent 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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 302 Found Location: /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-CRUD POST /distance HTTP/1.1 Host: www.mycompany.co.nz Accept: application/json Content-type: application/json;charset=UTF-8 { from: Auckland, NZL, to: Hamilton, NZL } or: GET /distance?from=...to=... HTTP/1.1 Host: www.mycompany.co.nz Accept: application/json HTTP/1.1 200 OK Content-length: 123 Content-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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Content-type: application/csv;charset=UTF-8 John Doe, 1 Main Street, Seattle, WA Jane Doe, 100 North Street, Los Angeles, CA HTTP/1.1 303 See other Location: /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 APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags 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 Stuļ¬€ HTTP Status codes ETags 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 important They 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 2xx 3xx 4xx 5xx ā†’ ā†’ ā†’ ā†’ ā†’ Informational Success Redirection Client error 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 Codes Important 2xx Codes 200 OK ā†’ Resource returned 201 Created ā†’ Resource created 204 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 Codes Important 3xx Codes 301 Moved Permanently ā†’ Resource reorganised 302 Found ā†’ Redirection for speciļ¬c object (e. g. search) 303 Other ā†’ A redirect due to an operation 304 Not modiļ¬ed ā†’ 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 Codes Important 4xx Codes 400 Bad request ā†’ Incorrect payload 401 Unauthorized ā†’ Not authorized to operate 403 Forbidden ā†’ Not authorized to operate 404 Not found ā†’ Resource was not found 405 Method not allowed ā†’ Method incorrect 406 Not acceptable ā†’ Cannot return in correct format 412 Precondition failed ā†’ ā€œETag mismatchā€ (418 Iā€™m a teapot ā†’ Hyper Text Coļ¬€ee 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 allowed 409 Conļ¬‚ict vs. 412 Precondition failed ā†’ deĀ·batĀ·aĀ·ble/diā€™bĀÆt b l/Adjective a 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.1 Host: www.mycompany.co.nz HTTP/1.1 200 OK Content-length: 12340 Content-type: application/json ETag: 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 Locking For Caching GET /blogpost/12345 HTTP/1.1 Host: www.mycompany.co.nz If-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 Locking For Concurrency Protection PATCH /blogpost/12345 HTTP/1.1 Host: www.mycompany.co.nz If-Match: abcd-1234 { author: Heinrich von Zinkeduetten } HTTP/1.1 412 Precondition failed Blog post was concurrently modiļ¬ed 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 APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags 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 Example Just to show you, it does work with XML, too. PUT /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+xml Authorization: OAuth ... booking flight/flight/15263/flight seat17F/seat mealhalal/meal /booking HTTP/1.1 200 OK Conent-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.1 Host: www.mycompany.co.nz Content-type: application/vnd.mycompany.myapp-v1+json { name: Teddybear, colour: red, stock: 15, price: { EUR: 15.95, NZD: 26.95 } } HTTP/1.1 201 Created Location: /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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 200 OK Content-length: 12345 Content-type: application/vnd.mycompany.myapp-v1.0+json Date: 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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 200 OK Content-length: 12345 Content-type: application/vnd.mycompany.myapp-v1.0+json ETag: 23709-12135125 Date: sun, 08 Aug 2013 12:34:56 NZST { name: Teddybear, manufacturer: Steiff, colour: red, stock: 30, ... } HTTP/1.1 404 Not found Content-length: 0 Date: 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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 204 No content Content-length: 0 Date: 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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json If-Match: 23709-12135125 { name: Teddybear, manufacturer: Steiff, colour: red, stock: 30, price: { EUR: 15.95, NZD: 26.95 } } HTTP/1.1 200 OK Content-length: 0 Date: sun, 08 Aug 2013 12:34:56 NZST HTTP/1.1 412 Precondition failed Content-length: 0 Date: 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 is an idempotent operation It (completely) replaces the content of the whole resource Consider PATCH for partial updates! PUT 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.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Content-type: application/csv;charset=UTF-8 John Doe, 1 Main Street, Seattle, WA Jane Doe, 100 North Street, Los Angeles, CA HTTP/1.1 303 See Other Location: /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 machines and business protocols ā†’ The HATEOAS constraint from REST What can be called ā€œRESTfulā€ depends on who you ask (itā€™s not a formally accepted deļ¬nition) Some say: You are not RESTful without hypermedia I say: REST is about Representational State Transfer, and hypermedia is an add-on (though very important) There are still good APIs without hypermedia (e. g. Amazon S3) 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 deļ¬nitely 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 services SOAP is more an RPC-style API (procedures with verb) REST is about REST (duh!) SOAP has strictly deļ¬ned interfaces, and the communication can be veriļ¬ed REST is more about evolving APIs, and making them explorable through hypermedia Bellsā€™nā€™whistles in SOAP, but can be found in REST (less obvious, less used: WADL, JSON schema, . . . ) Use . . . SOAP for well managed ā€œcorporate-styleā€ consumers REST for many, less-deļ¬ned ā€œ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 Transfer http://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 Reading Online 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
THANKS TO KIWI PYCON AUCKLAND 2013 THE YEAR OF THE SNAKE Kiwi PyCon 2013 will be held at Auckland University of Technology's new Sir Paul Reeves Building, also known as building AKL SIMPLICITY WG at AUT's city campus. SEPTEMBER FLEXIBILITY BEAUTY 6-8 New Zealand's premier Python event of the year http://nz.pycon.org/
Questions? Image used under Creative Commons from Boston Public Library http://flickr.com/boston_public_library/

More Related Content

PPTX
REST API
byTofazzal Ahmed
Ā 
PPTX
Introduction to REST - API
byChetan Gadodia
Ā 
PPTX
RESTful API - Best Practices
byTricode (part of Dept)
Ā 
PPTX
Best practices for RESTful web service design
byRamin Orujov
Ā 
PDF
[Spring Camp 2018] 11ė²ˆź°€ Spring Cloud źø°ė°˜ MSAė”œģ˜ ģ „ķ™˜ : ģ§€ė‚œ 1ė…„ź°„ģ˜ ģ“ģ•¼źø°
byYongSung Yoon
Ā 
PPTX
The RabbitMQ Message Broker
byMartin Toshev
Ā 
PPTX
Kong
byTroublemaker Khunpech
Ā 
PDF
REST API and CRUD
byPrem Sanil
Ā 
REST API
byTofazzal Ahmed
Ā 
Introduction to REST - API
byChetan Gadodia
Ā 
RESTful API - Best Practices
byTricode (part of Dept)
Ā 
Best practices for RESTful web service design
byRamin Orujov
Ā 
[Spring Camp 2018] 11ė²ˆź°€ Spring Cloud źø°ė°˜ MSAė”œģ˜ ģ „ķ™˜ : ģ§€ė‚œ 1ė…„ź°„ģ˜ ģ“ģ•¼źø°
byYongSung Yoon
Ā 
The RabbitMQ Message Broker
byMartin Toshev
Ā 
Kong
byTroublemaker Khunpech
Ā 
REST API and CRUD
byPrem Sanil
Ā 

What's hot

PPTX
Docker Kubernetes Istio
byAraf Karsh Hamid
Ā 
PDF
What is REST API? REST API Concepts and Examples | Edureka
byEdureka!
Ā 
PDF
Rest web services
byPaulo Gandra de Sousa
Ā 
PPTX
ELK Stack
byPhuc Nguyen
Ā 
PDF
Microservices
byTrieu Nguyen
Ā 
PPTX
Restful api
byAnurag Srivastava
Ā 
PPTX
Rest api-basic
byAmila Sampath
Ā 
PDF
Introduction to Apache Hive
byAvkash Chauhan
Ā 
PDF
Designing APIs with OpenAPI Spec
byAdam Paxton
Ā 
PDF
Apache Hudi: The Path Forward
byAlluxio, Inc.
Ā 
ODP
Stream processing using Kafka
byKnoldus Inc.
Ā 
PDF
[2019] PAYCO ģ‡¼ķ•‘ ė§ˆģ“ķ¬ė”œģ„œė¹„ģŠ¤ ģ•„ķ‚¤ķ…ģ²˜(MSA) ģ „ķ™˜źø°
byNHN FORWARD
Ā 
PPT
Understanding REST
byNitin Pande
Ā 
PDF
REST: From GET to HATEOAS
byJos Dirksen
Ā 
PDF
Spark (Structured) Streaming vs. Kafka Streams
byGuido Schmutz
Ā 
PPTX
Rest API
byRohana K Amarakoon
Ā 
PDF
Amazon OpenSearch Deep dive - ė‚“ė¶€źµ¬ģ”°, ģ„±ėŠ„ģµœģ ķ™” ź·øė¦¬ź³  ģŠ¤ģ¼€ģ¼ė§
byAmazon Web Services Korea
Ā 
PDF
Microservice Architecture Patterns, by Richard Langlois P. Eng.
byRichard Langlois P. Eng.
Ā 
ODP
OAuth2 - Introduction
byKnoldus Inc.
Ā 
PPTX
introduction about REST API
byAmilaSilva13
Ā 
Docker Kubernetes Istio
byAraf Karsh Hamid
Ā 
What is REST API? REST API Concepts and Examples | Edureka
byEdureka!
Ā 
Rest web services
byPaulo Gandra de Sousa
Ā 
ELK Stack
byPhuc Nguyen
Ā 
Microservices
byTrieu Nguyen
Ā 
Restful api
byAnurag Srivastava
Ā 
Rest api-basic
byAmila Sampath
Ā 
Introduction to Apache Hive
byAvkash Chauhan
Ā 
Designing APIs with OpenAPI Spec
byAdam Paxton
Ā 
Apache Hudi: The Path Forward
byAlluxio, Inc.
Ā 
Stream processing using Kafka
byKnoldus Inc.
Ā 
[2019] PAYCO ģ‡¼ķ•‘ ė§ˆģ“ķ¬ė”œģ„œė¹„ģŠ¤ ģ•„ķ‚¤ķ…ģ²˜(MSA) ģ „ķ™˜źø°
byNHN FORWARD
Ā 
Understanding REST
byNitin Pande
Ā 
REST: From GET to HATEOAS
byJos Dirksen
Ā 
Spark (Structured) Streaming vs. Kafka Streams
byGuido Schmutz
Ā 
Rest API
byRohana K Amarakoon
Ā 
Amazon OpenSearch Deep dive - ė‚“ė¶€źµ¬ģ”°, ģ„±ėŠ„ģµœģ ķ™” ź·øė¦¬ź³  ģŠ¤ģ¼€ģ¼ė§
byAmazon Web Services Korea
Ā 
Microservice Architecture Patterns, by Richard Langlois P. Eng.
byRichard Langlois P. Eng.
Ā 
OAuth2 - Introduction
byKnoldus Inc.
Ā 
introduction about REST API
byAmilaSilva13
Ā 

Viewers also liked

PDF
REST - Representational State Transfer
byPeter R. Egli
Ā 
PDF
Why HATEOAS
byLee Wayne
Ā 
PDF
Rest in practice con Symfony2
byDaniel Londero
Ā 
PPTX
Why Use ā€œRESTā€ Architecture for Web Services?
byArinto Murdopo
Ā 
PPTX
SOA Governance
byPrashant Kumar
Ā 
PPTX
Swagger APIs for Humans and Robots (Gluecon)
byTony Tam
Ā 
PPTX
Level 3 REST Makes Your API Browsable
byMatt Bishop
Ā 
PDF
The never-ending REST API design debate
byRestlet
Ā 
PPTX
Document your rest api using swagger - Devoxx 2015
byjohannes_fiala
Ā 
PPTX
Make Your API Irresistible
byduvander
Ā 
PPT
Soa Primer
byvavasthi
Ā 
PPTX
Introducing Swagger
byTony Tam
Ā 
PPTX
How to create a jQuery Modal Window
byLikno Software
Ā 
DOC
Lampiran unit root test
byChenk Alie Patrician
Ā 
DOCX
EQUITY MARKET INTEGRATION IN SELECTED MARKETS: EVIDENCE FROM UNIT ROOT AND CO...
byakjsk10
Ā 
PDF
Design patterns
byJason Austin
Ā 
PDF
Connect.Tech- Enhancing Your Workflow With Xcode Source Editor Extensions
bystable|kernel
Ā 
PDF
Purchasing power parity a unit root, cointegration and var analysis in emergi...
byGiwrgos Loukopoulos
Ā 
PDF
A Hypervisor IPS based on Hardware Assisted Virtualization Technology
byFFRI, Inc.
Ā 
PPTX
Creational pattern
byHimanshu
Ā 
REST - Representational State Transfer
byPeter R. Egli
Ā 
Why HATEOAS
byLee Wayne
Ā 
Rest in practice con Symfony2
byDaniel Londero
Ā 
Why Use ā€œRESTā€ Architecture for Web Services?
byArinto Murdopo
Ā 
SOA Governance
byPrashant Kumar
Ā 
Swagger APIs for Humans and Robots (Gluecon)
byTony Tam
Ā 
Level 3 REST Makes Your API Browsable
byMatt Bishop
Ā 
The never-ending REST API design debate
byRestlet
Ā 
Document your rest api using swagger - Devoxx 2015
byjohannes_fiala
Ā 
Make Your API Irresistible
byduvander
Ā 
Soa Primer
byvavasthi
Ā 
Introducing Swagger
byTony Tam
Ā 
How to create a jQuery Modal Window
byLikno Software
Ā 
Lampiran unit root test
byChenk Alie Patrician
Ā 
EQUITY MARKET INTEGRATION IN SELECTED MARKETS: EVIDENCE FROM UNIT ROOT AND CO...
byakjsk10
Ā 
Design patterns
byJason Austin
Ā 
Connect.Tech- Enhancing Your Workflow With Xcode Source Editor Extensions
bystable|kernel
Ā 
Purchasing power parity a unit root, cointegration and var analysis in emergi...
byGiwrgos Loukopoulos
Ā 
A Hypervisor IPS based on Hardware Assisted Virtualization Technology
byFFRI, Inc.
Ā 
Creational pattern
byHimanshu
Ā 

Similar to Representational State Transfer (REST) and HATEOAS

PPTX
REST Architecture with use case and example
byShailesh singh
Ā 
PPTX
REST Architecture with use case and example
byShailesh singh
Ā 
PPT
emilio.ppt
byMohit Joshi
Ā 
PPT
emilio.ppt
byDeepakKumar772882
Ā 
PPTX
REST and RESTful Services
byDamian T. Gordon
Ā 
PDF
Enterprise REST
byGanesh Prasad
Ā 
PDF
Rest - Representational State Transfer (EMC BRDC Internal Tech talk)
byRodrigo Senra
Ā 
PDF
Applications of the REST Principle
byelliando dias
Ā 
PPTX
Overview of REST - Raihan Ullah
byCefalo
Ā 
PDF
Restfulé£Žę ¼ĀžĀ„webęœåŠ”ęž¶ęž„
byBenjamin Tan
Ā 
PPTX
RESTful services
byPedram Bashiri
Ā 
PPTX
Principles of REST API Design
byTwo Sigma
Ā 
PPTX
REST & RESTful APIs: The State of Confusion
byGlenn Antoine
Ā 
PDF
What is REST?
bySaeid Zebardast
Ā 
PPTX
A REST API (also called a RESTful API or RESTful web API) is an application p...
byKongu Engineering College, Perundurai, Erode
Ā 
PDF
RESTful applications: The why and how by Maikel Mardjan
byJexia
Ā 
PPTX
Š”Š¼ŠøтрŠøŠ¹ ŠšŃ€Š°ŃŃƒŠ½: Š”ŠµŠ³Š¾Š“Š½Ń Š²Ń‹ уŠ¹Š“ŠµŃ‚Šµ с Š½Š¾Š²Ń‹Š¼ ŠæрŠµŠ“стŠ°Š²Š»ŠµŠ½ŠøŠµŠ¼ Š¾ REST
byOleg Poludnenko
Ā 
PDF
-overview of res tful architecture-2
byJunHwan Huh
Ā 
PPTX
RESTful APIs
byAdi Challa
Ā 
PPTX
REST != WebAPI
byDan (Danut) Prisacaru
Ā 
REST Architecture with use case and example
byShailesh singh
Ā 
REST Architecture with use case and example
byShailesh singh
Ā 
emilio.ppt
byMohit Joshi
Ā 
emilio.ppt
byDeepakKumar772882
Ā 
REST and RESTful Services
byDamian T. Gordon
Ā 
Enterprise REST
byGanesh Prasad
Ā 
Rest - Representational State Transfer (EMC BRDC Internal Tech talk)
byRodrigo Senra
Ā 
Applications of the REST Principle
byelliando dias
Ā 
Overview of REST - Raihan Ullah
byCefalo
Ā 
Restfulé£Žę ¼ĀžĀ„webęœåŠ”ęž¶ęž„
byBenjamin Tan
Ā 
RESTful services
byPedram Bashiri
Ā 
Principles of REST API Design
byTwo Sigma
Ā 
REST & RESTful APIs: The State of Confusion
byGlenn Antoine
Ā 
What is REST?
bySaeid Zebardast
Ā 
A REST API (also called a RESTful API or RESTful web API) is an application p...
byKongu Engineering College, Perundurai, Erode
Ā 
RESTful applications: The why and how by Maikel Mardjan
byJexia
Ā 
Š”Š¼ŠøтрŠøŠ¹ ŠšŃ€Š°ŃŃƒŠ½: Š”ŠµŠ³Š¾Š“Š½Ń Š²Ń‹ уŠ¹Š“ŠµŃ‚Šµ с Š½Š¾Š²Ń‹Š¼ ŠæрŠµŠ“стŠ°Š²Š»ŠµŠ½ŠøŠµŠ¼ Š¾ REST
byOleg Poludnenko
Ā 
-overview of res tful architecture-2
byJunHwan Huh
Ā 
RESTful APIs
byAdi Challa
Ā 
REST != WebAPI
byDan (Danut) Prisacaru
Ā 

More from Guy K. Kloss

PDF
Kauri ID - A Self-Sovereign, Blockchain-based Identity System
byGuy K. Kloss
Ā 
PDF
Qrious about Insights -- Big Data in the Real World
byGuy K. Kloss
Ā 
PDF
WTF is Blockchain???
byGuy K. Kloss
Ā 
PDF
Building a (Really) Secure Cloud Product
byGuy K. Kloss
Ā 
PDF
Introduction to LaTeX (For Word users)
byGuy K. Kloss
Ā 
PDF
MataNui - Building a Grid Data Infrastructure that "doesn't suck!"
byGuy K. Kloss
Ā 
PDF
Operations Research and Optimization in Python using PuLP
byGuy K. Kloss
Ā 
PDF
Python Data Plotting and Visualisation Extravaganza
byGuy K. Kloss
Ā 
PDF
Lecture "Open Source and Open Content"
byGuy K. Kloss
Ā 
PDF
Version Control with Subversion
byGuy K. Kloss
Ā 
PDF
Beating the (sh** out of the) GIL - Multithreading vs. Multiprocessing
byGuy K. Kloss
Ā 
PDF
Thinking Hybrid - Python/C++ Integration
byGuy K. Kloss
Ā 
PDF
Thinking Hybrid - Python/C++ Integration
byGuy K. Kloss
Ā 
PDF
Gaining Colour Stability in Live Image Capturing
byGuy K. Kloss
Ā 
PDF
LaTeX Introduction for Word Users
byGuy K. Kloss
Ā 
PDF
Thinking Hybrid - Python/C++ Integration
byGuy K. Kloss
Ā 
Kauri ID - A Self-Sovereign, Blockchain-based Identity System
byGuy K. Kloss
Ā 
Qrious about Insights -- Big Data in the Real World
byGuy K. Kloss
Ā 
WTF is Blockchain???
byGuy K. Kloss
Ā 
Building a (Really) Secure Cloud Product
byGuy K. Kloss
Ā 
Introduction to LaTeX (For Word users)
byGuy K. Kloss
Ā 
MataNui - Building a Grid Data Infrastructure that "doesn't suck!"
byGuy K. Kloss
Ā 
Operations Research and Optimization in Python using PuLP
byGuy K. Kloss
Ā 
Python Data Plotting and Visualisation Extravaganza
byGuy K. Kloss
Ā 
Lecture "Open Source and Open Content"
byGuy K. Kloss
Ā 
Version Control with Subversion
byGuy K. Kloss
Ā 
Beating the (sh** out of the) GIL - Multithreading vs. Multiprocessing
byGuy K. Kloss
Ā 
Thinking Hybrid - Python/C++ Integration
byGuy K. Kloss
Ā 
Thinking Hybrid - Python/C++ Integration
byGuy K. Kloss
Ā 
Gaining Colour Stability in Live Image Capturing
byGuy K. Kloss
Ā 
LaTeX Introduction for Word Users
byGuy K. Kloss
Ā 
Thinking Hybrid - Python/C++ Integration
byGuy K. Kloss
Ā 

Recently uploaded

PDF
Startup Formation Collapses While Acquisition Activity Hits New High!
byMemoori
Ā 
PDF
Designing a Blog Using Wordpress
bymarkzubi50
Ā 
PDF
Supercharge Your Copilot-Driven Collaboration with Microsoft 365 Agents SDK
byAntti Koskela
Ā 
PPTX
The Lex Wire Precedent: A Technical Standard for Machine-Mediated Authority ...
byJeff Howell
Ā 
PDF
UiPath Automation Developer Associate Training Series 2026 - Session 1
byDianaGray10
Ā 
PDF
Adapt.com Seed Fundraising Deck | The AI Computer for Business
byashley459565
Ā 
PDF
Post-Hackathon-Learnings-Maximizing-Impact-Beyond-the-Event.pdf
byishantyadav1111
Ā 
PDF
The Emergence of Empathic XR: AWE Asia 2026 keynote
byMark Billinghurst
Ā 
PPTX
Retrieval Augmented Generation- The Synergistic Power of Prompt Engineering
bySemantic SEO BD
Ā 
PPTX
TechSprint Inauguration at SJB Institute of Technology held on 18 December 2025
bysuhasspgdg
Ā 
PDF
Writing GPU-Ready AI Models in Pure Java with Babylon
byAna-Maria Mihalceanu
Ā 
PPTX
Authority After Search: How AI Systems Reconstruct Trust, Expertise, and Legi...
byJeff Howell
Ā 
PDF
Parental Control App for Phones_ The Complete 2026 Guide for Safer, Smarter P...
byRyan Cooper
Ā 
PDF
Advanced SELinux Management - RHCSA (RH134).pdf
byLinuxCert Guru
Ā 
PPTX
Introduction to Artificial Intelligence (AI).pptx
byammar414783
Ā 
PDF
Mesh WiFi Router: The Smart Solution for Fast, Seamless, Whole-Home Internet
byAeroMesh Systems
Ā 
PDF
AI and Zero Trust: What it takes to do it right
byMark Simos
Ā 
PDF
ICT500 - CRITICAL AND CREATIVE THINKING FOR INFORMATION TECHNOLOGY SOLUTIONS:...
by2024432452
Ā 
PDF
The Enterprise Web3 Landscape - a view from Kaleido based on the past 10 year...
byPeter Broadhurst
Ā 
PDF
Chapter 4 Network Security in computer security
byGetnet Tigabie Askale -(GM)
Ā 
Startup Formation Collapses While Acquisition Activity Hits New High!
byMemoori
Ā 
Designing a Blog Using Wordpress
bymarkzubi50
Ā 
Supercharge Your Copilot-Driven Collaboration with Microsoft 365 Agents SDK
byAntti Koskela
Ā 
The Lex Wire Precedent: A Technical Standard for Machine-Mediated Authority ...
byJeff Howell
Ā 
UiPath Automation Developer Associate Training Series 2026 - Session 1
byDianaGray10
Ā 
Adapt.com Seed Fundraising Deck | The AI Computer for Business
byashley459565
Ā 
Post-Hackathon-Learnings-Maximizing-Impact-Beyond-the-Event.pdf
byishantyadav1111
Ā 
The Emergence of Empathic XR: AWE Asia 2026 keynote
byMark Billinghurst
Ā 
Retrieval Augmented Generation- The Synergistic Power of Prompt Engineering
bySemantic SEO BD
Ā 
TechSprint Inauguration at SJB Institute of Technology held on 18 December 2025
bysuhasspgdg
Ā 
Writing GPU-Ready AI Models in Pure Java with Babylon
byAna-Maria Mihalceanu
Ā 
Authority After Search: How AI Systems Reconstruct Trust, Expertise, and Legi...
byJeff Howell
Ā 
Parental Control App for Phones_ The Complete 2026 Guide for Safer, Smarter P...
byRyan Cooper
Ā 
Advanced SELinux Management - RHCSA (RH134).pdf
byLinuxCert Guru
Ā 
Introduction to Artificial Intelligence (AI).pptx
byammar414783
Ā 
Mesh WiFi Router: The Smart Solution for Fast, Seamless, Whole-Home Internet
byAeroMesh Systems
Ā 
AI and Zero Trust: What it takes to do it right
byMark Simos
Ā 
ICT500 - CRITICAL AND CREATIVE THINKING FOR INFORMATION TECHNOLOGY SOLUTIONS:...
by2024432452
Ā 
The Enterprise Web3 Landscape - a view from Kaleido based on the past 10 year...
byPeter Broadhurst
Ā 
Chapter 4 Network Security in computer security
byGetnet Tigabie Askale -(GM)
Ā 

Representational State Transfer (REST) and HATEOAS

  • 1.
    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/
  • 2.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 2/84
  • 3.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 3/84
  • 4.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Warning before we start! REST != MVC Do 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
  • 5.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST? Roy Fielding, ā€œFatherā€ of REST REST is a coordinated set of architectural constraints that attempts to minimize latency and network communication while at the same time maximizing the independence and scalability of component implementations. This is achieved by placing constraints on connector semantics where other styles have focused on component semantics. REST enables the caching and reuse of interactions, dynamic substitutability of components, and processing of actions by intermediaries, thereby meeting the needs of an Internet-scale distributed hypermedia system. Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 5/84
  • 6.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST? REST is not a standard REST is not a protocol REST is an architectural style for networked applications REST deļ¬nes a set of simple principles (loosely followed by most API implementations) Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 6/84
  • 7.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST? Advantages of REST Cacheable Stateless Scalable Fault-tolerant Loosely coupled Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 7/84
  • 8.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST? Principles of REST URL identiļ¬es a resource URLs have a hierarchy Methods perform operations on resources Operation must be implicit Hypermedia format to represent data Link relations to navigate Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 8/84
  • 9.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST? The Four Main Principles 1 2 3 4 Identiļ¬cation of resources Manipulation of resources Self-descriptive messages HATEOAS Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 9/84
  • 10.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Identiļ¬cation of Resources You are doing it wrong . . . :-( /index.php?action=getarticleid=5 /default/article/5/4/6/size Cacheable? Scalable? Readable? Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 10/84
  • 11.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Identiļ¬cation of Resources Readable and Maintainable! /articles We want all articles /articles/5/photos/4/comments/1 We want the ļ¬rst comment of the fourth photo for the ļ¬fth article /articles/5/photos/4/comments We want all comments of the fourth photo for the ļ¬fth article Cacheable! Scalable! Readable! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 11/84
  • 12.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Identiļ¬cation of Resources Filtering through a Query String, not the URI /photos/order/size/limit/5 /photos?order=sizelimit=5 /photos/limit/5/order/size /photos?limit=5order=size Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 12/84
  • 13.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources Create Retrieve Update Delete But please note: REST != CRUD Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 13/84
  • 15.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources CRUD to HTTP verb mapping Create = POST Retrieve = GET Update = PUT (or Delete = DELETE PATCH) Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 15/84
  • 16.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources Creating a Resource creates a new resource But the server decides on that resources URI Examples POST 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
  • 17.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources Safe Methods Any client should be able to make the request . . . as many times as necessary GET, OPTIONS, HEAD Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 17/84
  • 18.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources Idempotent Methods Guarantees that the client can repeat the request when itā€™s not certain x++ vs. x=4 All methods except ā€œPOSTā€ Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 18/84
  • 19.
    REST APIs ExampleScenario 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
  • 20.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages How: Method GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce=123 ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 20/84
  • 21.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages How: Content-Type GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce=123 ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 21/84
  • 22.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages How: 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 others We wnat to ā€œplayā€ with API version 1.0 (not any other) General notes: Interpret requests generously Be strict with responses Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 22/84
  • 23.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages What GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce=123 ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 23/84
  • 24.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages When GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce=123 ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 24/84
  • 25.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages Who GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce=123 ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 25/84
  • 26.
    REST APIs ExampleScenario 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
  • 27.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages WADL? We can describe RESTful XML Web Services (similar to WSDL) Web Application Description Language (WADL) (another XML grammar to describe HTTP-based web applications) 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
  • 28.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples HATEOAS HATEOAS 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
  • 29.
    REST APIs ExampleScenario 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
  • 30.
    Image used underCreative Commons from oliverkendal http://flickr.com/oliverkendal/
  • 31.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Links Use links to allow clients to discover locations and operations Link relations are used to express options Clients do not need to know URLs This controls the state Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 31/84
  • 32.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Links Links contain (adapted from Atom formatā€™s link deļ¬nition): 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
  • 33.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 33/84
  • 34.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Flight Booking API State inside your REST API The HATEOAS links indicate state transitions Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 34/84
  • 35.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Search for Speciļ¬ed Flights POST /search?order=pricelimit=5 HTTP/1.1 Host: www.mycompany.co.nz Accept: 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
  • 36.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Returns a Collection of Flights HTTP/1.1 200 OK Content-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
  • 37.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Returns a Collection of Flights HTTP/1.1 200 OK Content-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
  • 38.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Conļ¬rm a Speciļ¬c Flight POST /booking HTTP/1.1 Host: www.mycompany.co.nz Accept: 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
  • 39.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Conļ¬rm a Speciļ¬c Flight . . . with more info POST /booking HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... { flight: /flight/15263, seat: 42A, meal: vegetarian } HTTP/1.1 201 Created Location: /booking/1616163 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 39/84
  • 40.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples What can we do with our booking? OPTIONS /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Authorization: OAuth ... HTTP/1.1 200 OK Allow: GET, PUT, DELETE Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 40/84
  • 41.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Cancel our booking! DELETE /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Authorization: OAuth ... HTTP/1.1 204 No content Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 41/84
  • 42.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Still need to Pay for the Flight GET /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... HTTP/1.1 200 OK Content-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
  • 43.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Pay through another resource POST /payment/booking HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: 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 Created Location: /payment/booking/54321 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 43/84
  • 44.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Canā€™t delete booking (already paid) OPTIONS /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Authorization: OAuth ... HTTP/1.1 200 OK Allow: GET Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 44/84
  • 45.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples We can fetch our e-Ticket now GET /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... HTTP/1.1 200 OK Content-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
  • 46.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 46/84
  • 47.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples (Common) Pitfalls of REST Design Versioning Methods in URI One URI per resource Controller resources non-CRUD Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 47/84
  • 48.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Versioning /api/v1.1/article/1234/photos /api/v1.2/article/1234/photos Diļ¬€erent resources? Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 48/84
  • 49.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Versioning OK: GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp+json ; version = 1.0 Better: GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1.1+json GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v5.0.4a+json Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 49/84
  • 50.
    REST APIs ExampleScenario 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
  • 51.
    REST APIs ExampleScenario 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
  • 52.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples One URI per Resource /api/article/1234 /api/article/red+teddybear Diļ¬€erent resources!?! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 52/84
  • 53.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples One URI per Resource If you must . . . GET /api/article/red+teddybear HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 302 Found Location: /api/article/1234 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 53/84
  • 54.
    REST APIs ExampleScenario 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
  • 55.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Controller Resources Non-CRUD POST /distance HTTP/1.1 Host: www.mycompany.co.nz Accept: application/json Content-type: application/json;charset=UTF-8 { from: Auckland, NZL, to: Hamilton, NZL } or: GET /distance?from=...to=... HTTP/1.1 Host: www.mycompany.co.nz Accept: application/json HTTP/1.1 200 OK Content-length: 123 Content-type: application/json { km: 127.5, miles: 78.9 } Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 55/84
  • 56.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Controller Resources Non-CRUD POST /user/gkloss/address_merge HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Content-type: application/csv;charset=UTF-8 John Doe, 1 Main Street, Seattle, WA Jane Doe, 100 North Street, Los Angeles, CA HTTP/1.1 303 See other Location: /user/gkloss/addressbook Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 56/84
  • 57.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 57/84
  • 58.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples More Important Stuļ¬€ HTTP Status codes ETags Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 58/84
  • 59.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes Status codes are important They 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
  • 60.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes 1xx 2xx 3xx 4xx 5xx ā†’ ā†’ ā†’ ā†’ ā†’ Informational Success Redirection Client error Server error Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 60/84
  • 61.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes Important 2xx Codes 200 OK ā†’ Resource returned 201 Created ā†’ Resource created 204 No content ā†’ Resource deleted Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 61/84
  • 62.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes Important 3xx Codes 301 Moved Permanently ā†’ Resource reorganised 302 Found ā†’ Redirection for speciļ¬c object (e. g. search) 303 Other ā†’ A redirect due to an operation 304 Not modiļ¬ed ā†’ Resource wasnā€™t changed Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 62/84
  • 63.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes Important 4xx Codes 400 Bad request ā†’ Incorrect payload 401 Unauthorized ā†’ Not authorized to operate 403 Forbidden ā†’ Not authorized to operate 404 Not found ā†’ Resource was not found 405 Method not allowed ā†’ Method incorrect 406 Not acceptable ā†’ Cannot return in correct format 412 Precondition failed ā†’ ā€œETag mismatchā€ (418 Iā€™m a teapot ā†’ Hyper Text Coļ¬€ee Pot Control Protocol) Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 63/84
  • 64.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes 501 Not implemented vs. 405 Method not allowed 409 Conļ¬‚ict vs. 412 Precondition failed ā†’ deĀ·batĀ·aĀ·ble/diā€™bĀÆt b l/Adjective a Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 64/84
  • 65.
    REST APIs ExampleScenario 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
  • 66.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples ETags Optimistic Locking GET /blogpost/12345 HTTP/1.1 Host: www.mycompany.co.nz HTTP/1.1 200 OK Content-length: 12340 Content-type: application/json ETag: abcd-1234 { author: Guy Kloss, title: Frobnification of Sub-Marine Vehicles, ... } Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 66/84
  • 67.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples ETags Optimistic Locking For Caching GET /blogpost/12345 HTTP/1.1 Host: www.mycompany.co.nz If-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
  • 68.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples ETags Optimistic Locking For Concurrency Protection PATCH /blogpost/12345 HTTP/1.1 Host: www.mycompany.co.nz If-Match: abcd-1234 { author: Heinrich von Zinkeduetten } HTTP/1.1 412 Precondition failed Blog post was concurrently modiļ¬ed by ā€œsomeoneā€ HTTP PATCH performs a partial update Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 68/84
  • 69.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identiļ¬cation of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 69/84
  • 70.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples An XML Example Just to show you, it does work with XML, too. PUT /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+xml Authorization: OAuth ... booking flight/flight/15263/flight seat17F/seat mealhalal/meal /booking HTTP/1.1 200 OK Conent-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
  • 71.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Creating a Resource POST /articles HTTP/1.1 Host: www.mycompany.co.nz Content-type: application/vnd.mycompany.myapp-v1+json { name: Teddybear, colour: red, stock: 15, price: { EUR: 15.95, NZD: 26.95 } } HTTP/1.1 201 Created Location: /articles/1234 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 71/84
  • 72.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Getting a Resource Collection GET /articles HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 200 OK Content-length: 12345 Content-type: application/vnd.mycompany.myapp-v1.0+json Date: 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
  • 73.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Getting a Resource GET /articles/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 200 OK Content-length: 12345 Content-type: application/vnd.mycompany.myapp-v1.0+json ETag: 23709-12135125 Date: sun, 08 Aug 2013 12:34:56 NZST { name: Teddybear, manufacturer: Steiff, colour: red, stock: 30, ... } HTTP/1.1 404 Not found Content-length: 0 Date: sun, 08 Aug 2013 12:34:56 NZST Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 73/84
  • 74.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Deleting a Resource DELETE /articles/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 204 No content Content-length: 0 Date: sun, 08 Aug 2013 12:34:56 NZST Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 74/84
  • 75.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Updating a Resource PUT /articles/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json If-Match: 23709-12135125 { name: Teddybear, manufacturer: Steiff, colour: red, stock: 30, price: { EUR: 15.95, NZD: 26.95 } } HTTP/1.1 200 OK Content-length: 0 Date: sun, 08 Aug 2013 12:34:56 NZST HTTP/1.1 412 Precondition failed Content-length: 0 Date: sun, 08 Aug 2013 12:34:56 NZST Idempotent! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 75/84
  • 76.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Updating a Resource is an idempotent operation It (completely) replaces the content of the whole resource Consider PATCH for partial updates! PUT Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 76/84
  • 77.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Controller Resources (Non-CRUD) Revisited . . . POST /user/gkloss/address_merge HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Content-type: application/csv;charset=UTF-8 John Doe, 1 Main Street, Seattle, WA Jane Doe, 100 North Street, Los Angeles, CA HTTP/1.1 303 See Other Location: /user/gkloss/addressbook Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 77/84
  • 78.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Conclusion Web-based services are about state machines and business protocols ā†’ The HATEOAS constraint from REST What can be called ā€œRESTfulā€ depends on who you ask (itā€™s not a formally accepted deļ¬nition) Some say: You are not RESTful without hypermedia I say: REST is about Representational State Transfer, and hypermedia is an add-on (though very important) There are still good APIs without hypermedia (e. g. Amazon S3) 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 deļ¬nitely no more than RESTish! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 78/84
  • 79.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Comparison REST vs. SOAP Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 79/84
  • 80.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples Comparison REST vs. SOAP Both are request/response type services SOAP is more an RPC-style API (procedures with verb) REST is about REST (duh!) SOAP has strictly deļ¬ned interfaces, and the communication can be veriļ¬ed REST is more about evolving APIs, and making them explorable through hypermedia Bellsā€™nā€™whistles in SOAP, but can be found in REST (less obvious, less used: WADL, JSON schema, . . . ) Use . . . SOAP for well managed ā€œcorporate-styleā€ consumers REST for many, less-deļ¬ned ā€œcitizen consumersā€ REST if the API is likely to evolve Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 80/84
  • 81.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples More Reading Wikipedia: Representational State Transfer http://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
  • 82.
    REST APIs ExampleScenario Pitfalls of REST Design More Leveraging HTTP REST Examples More Reading Online 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
  • 83.
    THANKS TO KIWI PYCON AUCKLAND2013 THE YEAR OF THE SNAKE Kiwi PyCon 2013 will be held at Auckland University of Technology's new Sir Paul Reeves Building, also known as building AKL SIMPLICITY WG at AUT's city campus. SEPTEMBER FLEXIBILITY BEAUTY 6-8 New Zealand's premier Python event of the year http://nz.pycon.org/
  • 84.
    Questions? Image used underCreative Commons from Boston Public Library http://flickr.com/boston_public_library/