Roy Fielding & hisdissertationOne of theprincipalauthorsof HTTP specCo-founder of Apache HTTP server projectWasheavilyinvolvedin HTML and URIsDissertationNo mention of CRUD or POSTLater Fielding saysinhisblogthateven HTTP itself is not a mandatory part of REST (but URI is)HATEOAS is more importantthan CRUD (hypertextdrivesappstatechanges; contentnegotiation)Layeredsystem: gateways, loadbalancers, firewalls, sharedcaches, etc.
Per Roy F: fromlevel 0-2 it’s not REST, 3 IS REST … thetermREST has beenmostlycoupledwithCRUD-likeaccesstodomainobjects0 – URI tunneling:oneURI, one HTTP method POST to a single URI, allattributesasparameter lookslike SOAP w/o envelope part of the Web, limited use of availablefeaturesFirewallfriendly (HTTP)Lackssophistication1 – resources … manyURIs, one HTTP method lots of thought-to-be-RESTfulservices stilltoocomplex2 – verbs … manyURIs, many HTTP methods verynice, butstill limited to CRUD scenariosonly3 – hypermedia resourcesdescribetheirowncapabilities and interconnections it’s like a HTML pagefromwhereyoucan go vialinks inadditiontolinks, it’s alsoaboutcontentnegotiation – own (MIME) types, dynamicdiscoveryLevel 1 tackles the question of handling complexity by using divide and conquer, breaking a large service endpoint down into multiple resources.Level 2 introduces a standard set of verbs so that we handle similar situations in the same way, removing unnecessary variation.Level 3 introduces discoverability, providing a way of making a protocol more self-documenting.
Itcan be anythingelsethan XML, really (JSON, YAML, etc)RPC-stylesolutionBasicallylike SOAP
PronounciationHate o’sHateyo’ assHate eeohsExamples:Get the second 50 items from 500, we may get a link back to the first 50 as well as the thirdWe get the resource data along with possible actions we may take upon it these actions may depend on my authority (authorization)http://www.soatothecloud.com/2012/04/api-gateway-support-for-hateoas-first.html great JSON example + mention of Gateway APIhttp://timelessrepo.com/haters-gonna-hateoas good XML example link tonew comment, commentstoblogentry + toselfproblems that it solves- w3c: coolurisdon’t change http://www.w3.org/Provider/Style/URI.htmlREST calls return with content in a requested format these formats have their media types with hints (links) as to what clients can do with the resource application state may change while „jumping” from one resource to another self-descriptive messagesREST APIs require the user to know that fixed URL structure (i.e. conventions) client rewrite is needed when API changesWith SOAP clients figure out what they can do with a given resource from the WSDL client-side (SOAP) vs server-side (HATEOAS) fixed vs dynamicproblems that it causesMany applications simply map their backend (DB) object to HTTP (api) resources != domain objects resources == domain objects + metadataNew resource definitions might (and should) have their own MIME typesProblemsPeopledon’t understandit’s a problemNo tooling for thisLinkscould be part of theresponseheader http://blog.steveklabnik.com/posts/2011-08-07-some-people-understand-rest-and-http
Each slot now has a link element which contains a URI to tell us how to book an appointment.
SOAPProtocolvsarchitecturalstyle SOAP has a standard whereas REST doesn’tOperationsvsresources verbsvsnounsRigid (typecheckingin SOAP – sometimesit’s a goodthing), light-weight (REST needs no wrapper, like XML in SOAP)Non-intuitivenessvssimplicity in REST URL describes almost everything and quiteintuitivetouse & modifySecurity: WS-Securityvs HTTPS/TLS message-levelvstunnel-levelsecurity http://blogs.msdn.com/b/vbertocci/archive/2005/04/25/end-to-end-security-or-why-you-shouldn-t-drive-your-motorcycle-naked.aspxWS-AtomicTransaction ACID transactions over a serviceManyproxiesblock PUT (badto REST)
Safety & Idempotencysafe: no side-effectsIdempotent: can be repeatedinsuccessionwithoutfailureGET is safe and idempotentPUT and DELETE arenotsafe, butidempotentPOST is neithersafenoridempotentAssociationbetweenresources: /owners/123/dogs don’t go deeperthan /resource/identifier/resourceUse ‚?’ for attributes /dogs?color=blackBe consistent, no mixed plurals&singularsConcretethingslikecoffee, beer NOT drink
api.company.comPut version # asmuchinthe front aspossibleMajor version # onlyDatesas version #s long, hardtoremember, whichdateformat?Optionalversioning and alwaystakethelatestifomitted
200 – OK201 – created204 – No content (after DELETE)400 – Badrequest401 – unauthorized403 – Forbidden404 – notfound405 – methodnotallowed500 – internalerror503 – Service unavailablewithRetry-AfterheaderUltimatelythefollowingthreeshould be enough: 200, 400 (pointingourwherevalidationfailed) and 500
Session managementCaching – reducenetworktraffic, loadon servers, latency, hidenetworkfailuresLocal cache + server cacheActions in the absence of resources use verbs, like /currencyconverter/convert?from=EUR&to=BYR&amount=1000
Thingsremovedfrom here tokeeptime:PATCH - http://weblog.rubyonrails.org/2012/2/26/edge-rails-patch-is-the-new-primary-http-method-for-updates noteveryoneknowswhat HTTP methodsare forParameters/attributes in URL or as part of HTTP header much easier to develop if in URLSuppress HTTP response codes usefulwhenourcode is runningin a containerthatintercepts HTTP commslike status codes
Wadl – web applicationdescriptionlanguage (W3.org), wadl2java tool
Spring Data REST (SDR) representsthebottom-upapproach, whereSDRcomesfromthedomainobjectlayer … it’s notreallyRESTful, imo
Has beenintheindustrysince 1998Developer, tester, architect, project managerMobile, enterpriseForum nokiachampion(?), blogger
Rest in practice
GETGábor Török @ EPAM/Szeged
Introduction, overview Best practices Java support
Roy T Fielding, PhD dissertation, 2000 Main characteristics ◦ Client-server ◦ Stateless ◦ Caching ◦ Layered architecture ◦ Code on demand ◦ URIs
Richardson’s Maturity Model Image courtesy of Martin Fowler
Plain Old XML (over HTTP) One URI, one method
POST /appointmentService HTTP/1.1<openSlotRequest date="2010-01-04" doctor="mjones"/>
Solves interop problems WSDL contract Strong typing Client- and server bindings Operations (i.e. verbs)WS-* support (Security, GETing/POSTing an XMLAtomicTransaction, etc.)Many proxies block PUT Non-intuitive Level 0
Resources vs actionsgetTickets vs /ticketsgetMusemTickets vs /tickets?type=museum
Plural + IDCRUD-style operationsConcrete not abstract namesResource GET POST PUT DELETE/tickets List tickets Create a Bulk update Delete all new ticket tickets/tickets/123 Get the Error Update a Delete a details of given ticket given ticket one ticket
http://api.company.com/cafe/v1 Major rev only Numbers, not nicknames, dates, etc.
HTTP status codes 200 403 500 503 204 200 400 201 400 500 404 405 401 Short description Pointer to more information