This document provides an overview of REST and best practices for REST API design. It discusses the core principles of REST, Richardson Maturity Model for REST API design, and examples demonstrating the different levels. It also covers Java support for REST APIs using JAX-RS and Spring frameworks. The document recommends practices like using plural nouns for resources and HTTP status codes for errors. It provides contact information for the author, Gábor Török, an experienced Solutions Architect.
21. W3: „Cool URIs don’t change”
vs
Roy Fielding: „A REST API must not define fixed
resource names or hierarchies”
HATEOAS & self-descriptive messages
Problems: people’s awareness, tools
24. Solves interop problems WSDL contract
Strong typing
Client- and server
bindings
Operations (i.e. verbs)
WS-* support (Security, GETing/POSTing an XML
AtomicTransaction, etc.)
Many proxies block PUT Non-intuitive
Level 0
25.
26. Resources vs actions
getTickets vs /tickets
getMusemTickets vs /tickets?type=museum
27. Plural + ID
CRUD-style operations
Concrete not abstract names
Resource 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
28. http://api.company.com/cafe/v1
Major rev only
Numbers, not nicknames, dates, etc.
29. HTTP status codes
200
403
500
503 204 200 400
201 400
500
404 405
401
Short description
Pointer to more information
43. Roy Fielding’s dissertation
REST in Practice from O’Reilly
Apigee blog & video tutorials
Articles, forums
44. Levels of REST – REST ≠ CRUD
Consistent view of best practices
Java support
45. Has been in the industry since late ’90s
Has been @EPAM since 2009, acted as a Dev
Lead/PM, now Solutions Architect
Has mobile + enterprise background
gabor.i.torok@gmail.com
Notas del editor
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