Your SlideShare is downloading. ×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Why Integrate using an API? | MuleSoft


Published on

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

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

Published in: Technology

1 Like
  • Be the first to comment

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

No notes for slide


  • 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 APIswe need to define what we are talking about, and then evaluate patterns
  • 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 PicturesNow that we are here, we underscore motivations to even bother with.
  • 6. COLLABORATE GROW ECOSYSTEM AND INNOVATEA Web API Study: Hurwitz;leads to integration -> stronger ecosystem -> more value > devices and applications in the ecosystem
  • 7. HOW TO ReST SOAP APIAt first glance, we might think how to present an api is rest vs soap
  • 8. HOW TO ReST WS-* APIit might really be the aspects of WS-* that would make such a decision, such as WS-Security,AtomicTransaction, ReliableMessaging
  • 9. HOW TO ReST ReST ish APISay we chose, ReST.. the thing is that ReST means a lot to many people
  • 10. HOW TO not-soap HATEOAS RESTends up being something between soap and hypertext driven
  • 11. To the Level 0: Level 1: Swamp of POX Resources glory Level 2: Level 3: Verbs Hypermedia of RESTLeonard Richardson circa 2008 Maturity Model
  • 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--Easiest example of POX is tunneling commands over a single http request/response paradigm
  • 13. RESOURCES > GET HTTP/1.1 < HTTP/1.1 200 OK <DeleteVolumeResponse xmlns=""> <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId> <return>true</return> </DeleteVolumeResponse> --snip-- Many URIs, same HTTP method Side-effects are API-specificmany uris, but a single invocation method. operations might be encoded in parameters, andresource might be mixed in with them
  • 14. VERBS > HEAD HTTP/1.1 < HTTP/1.1 200 OK HTTP verbs mean more than CRUD Status codes are meaningfulHEAD is metadata; PATCH is for update; PUT is replace; POST -> RPC/createatomicity underpins idempotence; by spec POST can affect multiple resources, but mostothers (except notably trace,options) only apply to the resource identified by the href
  • 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="" 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. abort add alternate disk:attach TRANSITIONS edit remove task All transitions are discoverable via linksHATEOAS is basically a state machine. Your responsibility is to not attempt any transitionundefined in links
  • 17. 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+xmlNew resources types can be added without breaking client, as can new fields/linksSource: Dan Feist
  • 18. ELEGENTclients alwaysknow transitionsself-documenting LETS USEand discoverableversion at HATEOASmedia-typegranularity
  • 19. Perceived Complexity?sometimes domain models are well defined, so the added value may be lost on the user
  • 20. Level 2 optimizes for Coarse Grained Versions CRUD++ Limited Representations Today’s Tools Simplicity over EleganceLeonard Richardson circa 2008 Maturity Model
  • 21. IS IT ALL JUST PRICKLES & GOO?Prickles & Goo: Alan Watts Trey Parker Matt StoneIs culture behind adoption of a particular rest approach? Even if the approach is correct, canyou persuade devs to adopt something they don’t want?
  • 22. KNOW What you need Who its for
  • 23. GOOD API DESIGNERS UNDERSTAND how it is used, and who will use it importance of iterations and feedback impacts to design beyond developmentdatabase details such as pagination, etctransition to a design that isn’t rest (aws)
  • 24. TWITTER IS NOT HATEOAS REST SEARCH STREAMoriginal has been around since 2008, latest update mainly addressed oauth and rate limitingchanges; thanks Greg Campbell for insight; api is versioned as 1.1, but includes 3 distinctapisaside: search can be modeled in HATEOAS, where POST is creation of search results, HEADreturns lifespan, etc
  • 25. AWS IS NOT REST AWS IS GOOD api designed to parse quickly simple extension (add new key) consistent security modelMany amazon web services do not even follow type 2 classifications, yet they are widelyadopted, and successful.. why is that? why do they not use rest?gurupa is the amazon http server, which is tuned for query parsing. language for extending itis simple (add a key), so parsing it to verify signature is just sort the keys and sign it.
  • 26. WebSockets is not Handshake is HTTPish Discoverable like ReST even Full-Duplex HTTP! Uncode or Binary Messages TCP ProtocolEx. ELB you have to use TCP/SSL as this is not a HTTP compatible protocolconsider impact for example lack of origin IP address, sticky sessionnew set of gateway products will emerge to support WebSockets
  • 27. 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 examplesdatabase details such as pagination, etc
  • 28. What now? ➡join api-craft ➡read The REST API Design Handbook ➡read Web API Design eBook ➡socialize your ideas Thank you!