> GET /problems/MONEY HTTP/1.1   I	 GOT	 99                                 PROBLEMS> Host: localhost> Accept: */*< HTTP/1...
PROBLEMS ➡Why API ➡ReST vs other HTTP APIs? ➡Design Patterns vs Real APIs
WHO	 IS	 THIS	 GUY?๏ @adrianfcole๏ architect CloudHub at MuleSoft๏founder jclouds
THANKS  ★     api-craft  ★     mattstep  ★   gtcampbell  ★       mulies
WHY	 WE	 API          photo copyright 2005 Sony Pictures
COLLABORATEGROW	 ECOSYSTEMAND	 INNOVATE
HOW	 TO	  ReST SOAPAPI
HOW	 TO	  ReST WS-*API
HOW	 TO	  ReST ReST   ishAPI
HOW	 TO	  not-soap   HATEOASREST
To	 the	         Level 0:        Level 1:                   Swamp of POX                   Resourcesglory	  Level 2:      ...
> POST /api HTTP/1.1                         > <SOAP-ENV:Envelope ...>                           <SOAP-ENV:Body>          ...
RESOURCES> GET https://ec2.amazonaws.com/?Action=DeleteVolume&VolumeId=vol-4282672b HTTP/1.1< HTTP/1.1 200 OK<DeleteVolume...
VERBS    > HEAD https://mybucket.s3.amazonaws.com/ HTTP/1.1    < HTTP/1.1 200 OK HTTP verbs mean more than CRUD    Status ...
HYPERMEDIA    > GET https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f-9dd4e03546    > Accept: application/vnd.vm...
What	 makes	 it	 HYPER?      ➡Base Type      ➡Links
abort                                                  add                                                  alternate     ...
CONTENT	 NEGOTIATION ➡   Client supplies representation in    Accept header ➡On change, update mediatype    name or annota...
Representing	 HyperMedia    Extend Atom    Opaque + Link Headers    HAL    ...
EXTEND	 ATOM      Vendor Type, Link elements      < HTTP/1.1 200 OK      < Content-Type: application/vnd.vmware.vcloud.cat...
Link	 Headers      Opaque Type, Link elements      < HTTP/1.1 200 OK      < Content-Type: image/jpeg      Link: </images/f...
Hypertext	 Application	 Language     Mix-in hypermedia controls into base type     embed resources for efficiency     < HT...
ELEGENTclients alwaysknow transitionsself-documenting                   LETS	 USEand discoverableversion at               ...
Perceived	 Complexity?
Level	 2	 optimizes	 for Coarse Grained Versions    CRUD++    Limited Representations    Today’s Tools    Simplicity over ...
IS	 IT	 ALL	 JUST	 PRICKLES	 &	 GOO?
can	 we	 have	 both?
There	       Domain	 Style           Base	 Formatis	 no	      State	 TransferLevel2          App	 Flow Design            p...
REST	 Design	 tools       ➡Apiary       ➡Swagger       ➡iodocs
GOOD	 API	 DESIGNERS	 UNDERSTAND how it is used, and who will use it importance of iterations and feedback impacts to desi...
TWITTER	 IS	 NOT	 HATEOAS         REST         SEARCH         STREAM
AWS	 IS	 NOT	 REST	 AWS	 IS	 GOODapi designed to parse quicklysimple extension (add new key)consistent security modelbulk ...
WebSockets	 	 ain’t	 evenHTTP! Handshake is HTTPish      Discoverable like ReST      Full-Duplex      Uncode or Binary Mes...
GOOD	 REST	 APIsAre consciously designedVersion at the right scopeDon’t leak implementation detailsUse auth models relevan...
What	 now? ➡join api-craft ➡read The REST API Design Handbook ➡read Building Hypermedia APIs... ➡socialize your ideas     ...
Upcoming SlideShare
Loading in …5
×

I got 99 problems, but ReST ain't one

5,747 views

Published on

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

Published in: Technology
1 Comment
19 Likes
Statistics
Notes
No Downloads
Views
Total views
5,747
On SlideShare
0
From Embeds
0
Number of Embeds
299
Actions
Shares
0
Downloads
0
Comments
1
Likes
19
Embeds 0
No embeds

No notes for slide
  • \n
  • we need to define what we are talking about, and then evaluate patterns\n
  • \n
  • \n
  • Now that we are here, we underscore motivations to even bother with.\n
  • A Web API Study: Hurwitz;\n leads to integration -&gt; stronger ecosystem -&gt; more value\n &gt; devices and applications in the ecosystem\n\n
  • At first glance, we might think how to present an api is rest vs soap\n
  • it might really be the aspects of WS-* that would make such a decision, such as WS-Security, AtomicTransaction, ReliableMessaging\n
  • Say we chose, ReST.. the thing is that ReST means a lot to many people\n
  • ends up being something between soap and hypertext driven\n
  • Leonard Richardson circa 2008 Maturity Model\n
  • Easiest example of POX is tunneling commands over a single http request/response paradigm\n
  • many uris, but a single invocation method. operations might be encoded in parameters, and resource might be mixed in with them\n
  • HEAD is metadata; PATCH is for update; PUT is replace; POST -&gt; 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
  • \n
  • \n
  • HATEOAS is basically a state machine. Your responsibility is to not attempt any transition undefined in links\n
  • 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
  • There are other ways, too...\nxlink can decorate in namespace of xml, but doesn&amp;#x2019;t expose representations\ncollection+json is an interesting approach for managing collections (includes its own data format)\n
  • \n
  • ex. cache intermediaries http://tools.ietf.org/html/draft-nottingham-linked-cache-inv-03\n
  • 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
  • \n
  • sometimes domain models are well defined, so the added value may be lost on the user\n
  • Leonard Richardson circa 2008 Maturity Model\n
  • Prickles &amp; 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&amp;#x2019;t want?\n
  • we are probably at various intervals on the same plane. more detail == overly complex. not enough == naive.\n
  • Amundsen, Mike (2011-11-22). Building Hypermedia APIs with HTML5 and Node (p. 20). OReilly Media - A. Kindle Edition. \n
  • http://apiary.io/ &lt; markdown extension describes behavior, generates mock and tests it\nhttp://swagger.wordnik.com/ &lt;- json describes resource, apis, models, generates many clients\nhttps://github.com/mashery/iodocs &lt;- json describes service, apis, creates javascript client\n
  • database details such as pagination, etc\n\ntransition to a design that isn&amp;#x2019;t rest (aws)\n
  • 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
  • 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
  • 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
  • database details such as pagination, etc\n
  • \n
  • 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!

    ×