Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

I got 99 problems, but ReST ain't one

7,258 views

Published on

Review of Web, Query, and HATEOAS designs many call ReST. Motivations behind choices.

Published in: Technology

I got 99 problems, but ReST ain't one

  1. 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. 2. PROBLEMS ➡Why API ➡ReST vs other HTTP APIs? ➡Design Patterns vs Real APIs
  3. 3. WHO IS THIS GUY?๏ @adrianfcole๏ architect CloudHub at MuleSoft๏founder jclouds
  4. 4. THANKS ★ api-craft ★ mattstep ★ gtcampbell ★ mulies
  5. 5. WHY WE API photo copyright 2005 Sony Pictures
  6. 6. COLLABORATEGROW ECOSYSTEMAND INNOVATE
  7. 7. HOW TO ReST SOAPAPI
  8. 8. HOW TO ReST WS-*API
  9. 9. HOW TO ReST ReST ishAPI
  10. 10. HOW TO not-soap HATEOASREST
  11. 11. To the Level 0: Level 1: Swamp of POX Resourcesglory Level 2: Level 3: Verbs Hypermediaof REST
  12. 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. 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. 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. 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. 16. What makes it HYPER? ➡Base Type ➡Links
  17. 17. abort add alternate disk:attach TRANSITIONS edit remove taskAll transitions are discoverable via links
  18. 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. 19. Representing HyperMedia Extend Atom Opaque + Link Headers HAL ...
  20. 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 typesinherits link semantics from Atom
  21. 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 typesfacilitates intermediaries
  22. 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. 23. ELEGENTclients alwaysknow transitionsself-documenting LETS USEand discoverableversion at HATEOASmedia-typegranularity
  24. 24. Perceived Complexity?
  25. 25. Level 2 optimizes for Coarse Grained Versions CRUD++ Limited Representations Today’s Tools Simplicity over Elegance
  26. 26. IS IT ALL JUST PRICKLES & GOO?
  27. 27. can we have both?
  28. 28. There Domain Style Base Formatis no State TransferLevel2 App Flow Design plus stuff like errors
  29. 29. REST Design tools ➡Apiary ➡Swagger ➡iodocs
  30. 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. 31. TWITTER IS NOT HATEOAS REST SEARCH STREAM
  32. 32. AWS IS NOT REST AWS IS GOODapi designed to parse quicklysimple extension (add new key)consistent security modelbulk ops
  33. 33. WebSockets ain’t evenHTTP! Handshake is HTTPish Discoverable like ReST Full-Duplex Uncode or Binary Messages TCP Protocol
  34. 34. GOOD REST APIsAre consciously designedVersion at the right scopeDon’t leak implementation detailsUse auth models relevant to consumerAre well documented with examples
  35. 35. What now? ➡join api-craft ➡read The REST API Design Handbook ➡read Building Hypermedia APIs... ➡socialize your ideas Thank you!

×