Why Integrate using an API? | MuleSoft
4 likes1,690 views
The document discusses REST APIs and design patterns. It provides examples of APIs that do and do not strictly follow REST principles, but can still be successful. It emphasizes that good API design considers how the API will actually be used and iteratively incorporates feedback. APIs need not follow all REST principles to be effective if they meet the real needs of their users and are 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--
Easiest example of POX is tunneling commands over a single http request/response paradigm](https://image.slidesharecdn.com/99problems-121107125753-phpapp01/85/Why-Integrate-using-an-API-MuleSoft-12-320.jpg)
Why Integrate using an API? | MuleSoft
- 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 we 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 Pictures Now that we are here, we underscore motivations to even bother with.
- 6. COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications in the ecosystem
- 7. HOW TO ReST SOAP API At first glance, we might think how to present an api is rest vs soap
- 8. HOW TO ReST WS-* API it 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 API Say we chose, ReST.. the thing is that ReST means a lot to many people
- 10. HOW TO not-soap HATEOAS REST ends 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 REST Leonard 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 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 many uris, but a single invocation method. operations might be encoded in parameters, and resource might be mixed in with them
- 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 HEAD is metadata; PATCH is for update; PUT is replace; POST -> RPC/create atomicity 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
- 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. abort add alternate disk:attach TRANSITIONS edit remove task All transitions are discoverable via links HATEOAS is basically a state machine. Your responsibility is to not attempt any transition undefined 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+xml New resources types can be added without breaking client, as can new fields/links Source: Dan Feist
- 18. ELEGENT clients always know transitions self-documenting LETS USE and discoverable version at HATEOAS media-type granularity
- 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 Elegance Leonard Richardson circa 2008 Maturity Model
- 21. IS IT ALL JUST PRICKLES & GOO? Prickles & Goo: Alan Watts Trey Parker Matt Stone Is culture behind adoption of a particular rest approach? Even if the approach is correct, can you 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 development database details such as pagination, etc transition to a design that isn’t rest (aws)
- 24. TWITTER IS NOT HATEOAS REST SEARCH STREAM 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 aside: search can be modeled in HATEOAS, where POST is creation of search results, HEAD returns lifespan, etc
- 25. AWS IS NOT REST AWS IS GOOD api designed to parse quickly simple extension (add new key) consistent security model 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? gurupa 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.
- 26. WebSockets is not Handshake is HTTPish Discoverable like ReST even Full-Duplex HTTP! Uncode or Binary Messages TCP Protocol Ex. ELB you have to use TCP/SSL as this is not a HTTP compatible protocol consider impact for example lack of origin IP address, sticky session new 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 examples database 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!