I got 99 problems, but ReST ain't one
23 likes9,286 views
The document discusses REST API design principles and best practices. It begins by providing examples of RESTful API requests and responses. It then covers REST concepts like resources, verbs, hypermedia, content negotiation, and representation formats. The document advocates for designing APIs that are self-documenting through hypermedia and embedding links to allow discovery of available state transitions and actions. It also discusses balancing REST purism with pragmatic design choices and notes that many popular APIs are not purely RESTful but are still well-designed.
![> POST /api HTTP/1.1
> <SOAP-ENV:Envelope ...>
<SOAP-ENV:Body>
<m:getAvailableDataSources xmlns:m="
Swamp
<group xsi:type="xsd:string">ArcWe
<service xsi:type="xsd:string">Map
<token xsi:type="xsd:string">MyTok
</m:getAvailableDataSources>
of POX
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
< HTTP/1.1 200 OK
< <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope ...>
<soap:Body>
<n:getAvailableDataSourcesResponse x
<Result href="#id0"/>
</n:getAvailableDataSourcesResponse>
All things go over the <id0 id="id0" soapenc:root="0" xsi:t
soapenc:arrayType="ns5:DataSource[21]">
same endpoint as XML <i href="#id1"/>
--snip--](https://image.slidesharecdn.com/99problems-121003122856-phpapp01/85/I-got-99-problems-but-ReST-ain-t-one-12-320.jpg)
I got 99 problems, but ReST ain't one
- 1. > GET /problems/MONEY HTTP/1.1 I GOT 99 PROBLEMS > Host: localhost > Accept: */* < HTTP/1.1 200 OK > GET /problems/POWER HTTP/1.1 > Host: localhost BUT REST AINT ONE > Accept: */* < HTTP/1.1 200 OK > GET /problems/REST HTTP/1.1 > Host: localhost > Accept: */* @adrianfcole < HTTP/1.1 404 Not Found
- 2. PROBLEMS ➡Why API ➡ReST vs other HTTP APIs? ➡Design Patterns vs Real APIs
- 3. WHO IS THIS GUY? ๏ @adrianfcole ๏ architect CloudHub at MuleSoft ๏founder jclouds
- 4. THANKS ★ api-craft ★ mattstep ★ gtcampbell ★ mulies
- 5. WHY WE API photo copyright 2005 Sony Pictures
- 7. HOW TO ReST SOAP API
- 8. HOW TO ReST WS-* API
- 9. HOW TO ReST ReST ish API
- 10. HOW TO not-soap HATEOAS REST
- 11. To the Level 0: Level 1: Swamp of POX Resources glory Level 2: Level 3: Verbs Hypermedia of REST
- 12. > POST /api HTTP/1.1 > <SOAP-ENV:Envelope ...> <SOAP-ENV:Body> <m:getAvailableDataSources xmlns:m=" Swamp <group xsi:type="xsd:string">ArcWe <service xsi:type="xsd:string">Map <token xsi:type="xsd:string">MyTok </m:getAvailableDataSources> of POX </SOAP-ENV:Body> </SOAP-ENV:Envelope> < HTTP/1.1 200 OK < <?xml version="1.0" encoding="UTF-8"?> <soap:Envelope ...> <soap:Body> <n:getAvailableDataSourcesResponse x <Result href="#id0"/> </n:getAvailableDataSourcesResponse> All things go over the <id0 id="id0" soapenc:root="0" xsi:t soapenc:arrayType="ns5:DataSource[21]"> same endpoint as XML <i href="#id1"/> --snip--
- 13. RESOURCES > GET https://ec2.amazonaws.com/?Action=DeleteVolume&VolumeId=vol-4282672b HTTP/1.1 < HTTP/1.1 200 OK <DeleteVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2012-08-15/"> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteVolumeResponse> --snip-- Many URIs, same HTTP method Side-effects are API-specific
- 14. VERBS > HEAD https://mybucket.s3.amazonaws.com/ HTTP/1.1 < HTTP/1.1 200 OK HTTP verbs mean more than CRUD Status codes are meaningful
- 15. HYPERMEDIA > GET https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f-9dd4e03546 > Accept: application/vnd.vmware.vcloud.catalogItem+xml < HTTP/1.1 200 OK < Content-Type: application/vnd.vmware.vcloud.catalogItem+xml;version=1.0 <CatalogItem xmlns="http://www.vmware.com/vcloud/v1" name="mycatalog" type=" href="https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a5 <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud/api/v1.0/catalog/7f192dfe-00d1-42f2-9f76-9360 <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f- <Link rel="remove" href="https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f-9 --snip-- Discoverability, Self-documenting
- 16. What makes it HYPER? ➡Base Type ➡Links
- 17. abort add alternate disk:attach TRANSITIONS edit remove task All transitions are discoverable via links
- 18. CONTENT NEGOTIATION ➡ Client supplies representation in Accept header ➡On change, update mediatype name or annotate via ;version=N.N ➡On overhaul, bump global version Accept: application/vnd.VENDOR.PRODUCT.RESOURCE+xml
- 19. Representing HyperMedia Extend Atom Opaque + Link Headers HAL ...
- 20. EXTEND ATOM Vendor Type, Link elements < HTTP/1.1 200 OK < Content-Type: application/vnd.vmware.vcloud.catalogItem+xml;version=1.0 <CatalogItem xmlns="http://www.vmware.com/vcloud/v1" name="mycatalog" type=" href="https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a5 <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud/api/v1.0/catalog/7f192dfe-00d1-42f2-9f76-9360 <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f- <Link rel="remove" href="https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f-9 --snip-- domain-specific types inherits link semantics from Atom
- 21. Link Headers Opaque Type, Link elements < HTTP/1.1 200 OK < Content-Type: image/jpeg Link: </images/foo.png>; rel="alternate"; type=”image/png” 010101010101010101 --snip-- supports binary types facilitates intermediaries
- 22. Hypertext Application Language Mix-in hypermedia controls into base type embed resources for efficiency < HTTP/1.1 200 OK < Content-Type: application/hal+json { _links: { self: { href: '/example', } }, _embedded: {}, name: 'foo', --snip-- domain-specific type agnostic
- 23. ELEGENT clients always know transitions self-documenting LETS USE and discoverable version at HATEOAS media-type granularity
- 25. Level 2 optimizes for Coarse Grained Versions CRUD++ Limited Representations Today’s Tools Simplicity over Elegance
- 26. IS IT ALL JUST PRICKLES & GOO?
- 27. can we have both?
- 28. There Domain Style Base Format is no State Transfer Level2 App Flow Design plus stuff like errors
- 29. REST Design tools ➡Apiary ➡Swagger ➡iodocs
- 30. GOOD API DESIGNERS UNDERSTAND how it is used, and who will use it importance of iterations and feedback impacts to design beyond development there’s no golden hammer (not even mongo)
- 31. TWITTER IS NOT HATEOAS REST SEARCH STREAM
- 32. AWS IS NOT REST AWS IS GOOD api designed to parse quickly simple extension (add new key) consistent security model bulk ops
- 33. WebSockets ain’t even HTTP! Handshake is HTTPish Discoverable like ReST Full-Duplex Uncode or Binary Messages TCP Protocol
- 34. GOOD REST APIs Are consciously designed Version at the right scope Don’t leak implementation details Use auth models relevant to consumer Are well documented with examples
- 35. What now? ➡join api-craft ➡read The REST API Design Handbook ➡read Building Hypermedia APIs... ➡socialize your ideas Thank you!
Editor's Notes
- #2: \n
- #3: we need to define what we are talking about, and then evaluate patterns\n
- #4: \n
- #5: \n
- #6: Now that we are here, we underscore motivations to even bother with.\n
- #7: A Web API Study: Hurwitz;\n leads to integration -> stronger ecosystem -> more value\n > devices and applications in the ecosystem\n\n
- #8: At first glance, we might think how to present an api is rest vs soap\n
- #9: it might really be the aspects of WS-* that would make such a decision, such as WS-Security, AtomicTransaction, ReliableMessaging\n
- #10: Say we chose, ReST.. the thing is that ReST means a lot to many people\n
- #11: ends up being something between soap and hypertext driven\n
- #12: Leonard Richardson circa 2008 Maturity Model\n
- #13: Easiest example of POX is tunneling commands over a single http request/response paradigm\n
- #14: many uris, but a single invocation method. operations might be encoded in parameters, and resource might be mixed in with them\n
- #15: HEAD is metadata; PATCH is for update; PUT is replace; POST -> RPC/create\natomicity underpins idempotence; by spec POST can affect multiple resources, but most others (except notably trace,options) only apply to the resource identified by the href\n
- #16: \n
- #17: \n
- #18: HATEOAS is basically a state machine. Your responsibility is to not attempt any transition undefined in links\n
- #19: New resources types can be added without breaking client, as can new fields/links\nabove pattern recommended by: Dan Feist\n\nOther option you can use is link with profile relation.\n
- #20: There are other ways, too...\nxlink can decorate in namespace of xml, but doesn&#x2019;t expose representations\ncollection+json is an interesting approach for managing collections (includes its own data format)\n
- #21: \n
- #22: ex. cache intermediaries http://tools.ietf.org/html/draft-nottingham-linked-cache-inv-03\n
- #23: define domain-specific type using type link parameter, or via custom rel or profile link (preferred)\nhttp://tools.ietf.org/id/draft-kelly-json-hal\nalso supports templated urls such as queries\n
- #24: \n
- #25: sometimes domain models are well defined, so the added value may be lost on the user\n
- #26: Leonard Richardson circa 2008 Maturity Model\n
- #27: Prickles & Goo: Alan Watts Trey Parker Matt Stone\nIs culture behind adoption of a particular rest approach? Even if the approach is correct, can you persuade devs to adopt something they don&#x2019;t want?\n
- #28: we are probably at various intervals on the same plane. more detail == overly complex. not enough == naive.\n
- #29: Amundsen, Mike (2011-11-22). Building Hypermedia APIs with HTML5 and Node (p. 20). OReilly Media - A. Kindle Edition. \n
- #30: http://apiary.io/ < markdown extension describes behavior, generates mock and tests it\nhttp://swagger.wordnik.com/ <- json describes resource, apis, models, generates many clients\nhttps://github.com/mashery/iodocs <- json describes service, apis, creates javascript client\n
- #31: database details such as pagination, etc\n\ntransition to a design that isn&#x2019;t rest (aws)\n
- #32: original has been around since 2008, latest update mainly addressed oauth and rate limiting changes; thanks Greg Campbell for insight; api is versioned as 1.1, but includes 3 distinct apis\naside: search can be modeled in HATEOAS, where POST is creation of search results, HEAD returns lifespan, etc\n\n
- #33: Many amazon web services do not even follow type 2 classifications, yet they are widely adopted, and successful.. why is that? why do they not use rest?\n\ngurupa is the amazon http server, which is tuned for query parsing. language for extending it is simple (add a key), so parsing it to verify signature is just sort the keys and sign it.\n\nbulk ops like s3 multi-delete help deal with very large problems.\n
- #34: Ex. ELB you have to use TCP/SSL as this is not a HTTP compatible protocol\nconsider impact for example lack of origin IP address, sticky session\nnew set of gateway products will emerge to support WebSockets\n
- #35: database details such as pagination, etc\n
- #36: \n