IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study:...
Transcript of IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study:...
![Page 1: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/1.jpg)
I GOT 99PROBLEMSBUT RESTAINT ONE
> GET /problems/REST HTTP/1.1> Host: localhost> Accept: */*
< HTTP/1.1 404 Not Found
> GET /problems/POWER HTTP/1.1> Host: localhost> Accept: */*
< HTTP/1.1 200 OK
> GET /problems/MONEY HTTP/1.1> Host: localhost> Accept: */*
< HTTP/1.1 200 OK
@adrianfcole
![Page 2: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/2.jpg)
➡Why API
➡ReST vs other HTTP APIs?
➡Design Patterns vs Real APIs
PROBLEMS
we need to define what we are talking about, and then evaluate patterns
![Page 3: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/3.jpg)
๏@adrianfcole
๏architect CloudHub at MuleSoft
๏founder jclouds
WHO IS THIS GUY?
![Page 4: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/4.jpg)
THANKS★ api-craft
★ mattstep
★ gtcampbell
★ mulies
![Page 5: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/5.jpg)
photo copyright 2005 Sony Pictures
WHY WE API
Now that we are here, we underscore motivations to even bother with.
![Page 6: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/6.jpg)
COLLABORATEGROW ECOSYSTEMAND INNOVATE
A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications in the ecosystem
![Page 7: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/7.jpg)
HOW TO API
ReST SOAP
At first glance, we might think how to present an api is rest vs soap
![Page 8: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/8.jpg)
HOW TO API
ReST WS-*
it might really be the aspects of WS-* that would make such a decision, such as WS-Security, AtomicTransaction, ReliableMessaging
![Page 9: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/9.jpg)
HOW TO API
ReST ReSTish
Say we chose, ReST.. the thing is that ReST means a lot to many people
![Page 10: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/10.jpg)
HOW TO REST
HATEOASnot-soap
ends up being something between soap and hypertext driven
![Page 11: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/11.jpg)
To the glory of REST
Level 0: Swamp of POXLevel 1: ResourcesLevel 2: VerbsLevel 3: Hypermedia
Leonard Richardson circa 2008 Maturity Model
![Page 12: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/12.jpg)
Swamp of POX
> POST /api HTTP/1.1> <SOAP-ENV:Envelope ...> <SOAP-ENV:Body> <m:getAvailableDataSources xmlns:m="http://arcweb.esri.com/v2"> <group xsi:type="xsd:string">ArcWebForDev</group> <service xsi:type="xsd:string">MapImage</service> <token xsi:type="xsd:string">MyToken</token> </m:getAvailableDataSources> </SOAP-ENV:Body></SOAP-ENV:Envelope>
< HTTP/1.1 200 OK< <?xml version="1.0" encoding="UTF-8"?><soap:Envelope ...> <soap:Body> <n:getAvailableDataSourcesResponse xmlns:n="http://arcweb.esri.com/v2"> <Result href="#id0"/> </n:getAvailableDataSourcesResponse> <id0 id="id0" soapenc:root="0" xsi:type="soapenc:Array" soapenc:arrayType="ns5:DataSource[21]"> <i href="#id1"/>--snip--
All things go over the same endpoint as XML
Easiest example of POX is tunneling commands over a single http request/response paradigm
![Page 13: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/13.jpg)
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 methodSide-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
![Page 14: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/14.jpg)
VERBS
HTTP verbs mean more than CRUDStatus codes are meaningful
> HEAD https://mybucket.s3.amazonaws.com/ HTTP/1.1
< HTTP/1.1 200 OK
HEAD is metadata; PATCH is for update; PUT is replace; POST -> RPC/createatomicity 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
![Page 15: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/15.jpg)
HYPERMEDIA
Discoverability, Self-documenting
> GET https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f-9dd4e03546bc HTTP/1.1> 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="application/vnd.vmware.vcloud.catalogItem+xml" href="https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f-9dd4e03546bc"> <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="https://vcloud/api/v1.0/catalog/7f192dfe-00d1-42f2-9f76-93601fc8662a"/> <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f-9dd4e03546bc"/> <Link rel="remove" href="https://vcloud/api/v1.0/catalogItem/1c01defe-1111-42ac-a50f-9dd4e03546bc"/> --snip--
![Page 16: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/16.jpg)
TRANSITIONS
All transitions are discoverable via links
abort
add
alternate
disk:attach
edit
remove
task
HATEOAS is basically a state machine. Your responsibility is to not attempt any transition undefined in links
![Page 17: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/17.jpg)
➡Client supplies representation in Accept header
➡On change, update mediatype name or annotate via ;version=N.N
➡On overhaul, bump global version
CONTENT NEGOTIATION
Accept: application/vnd.VENDOR.PRODUCT.RESOURCE+xml
New resources types can be added without breaking client, as can new fields/linksSource: Dan Feist
![Page 18: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/18.jpg)
LETS USEHATEOAS
clients always know transitions
self-documenting and discoverable
version at media-type granularity
ELEGENT
![Page 19: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/19.jpg)
Perceived Complexity?
sometimes domain models are well defined, so the added value may be lost on the user
![Page 20: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/20.jpg)
Level 2 optimizes for Coarse Grained Versions
CRUD++Limited RepresentationsToday’s ToolsSimplicity over Elegance
Leonard Richardson circa 2008 Maturity Model
![Page 21: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/21.jpg)
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, can you persuade devs to adopt something they don’t want?
![Page 22: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/22.jpg)
KNOW What you need
Who its for
![Page 23: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/23.jpg)
how it is used, and who will use it
importance of iterations and feedback
impacts to design beyond development
GOOD API DESIGNERS UNDERSTAND
database details such as pagination, etc
transition to a design that isn’t rest (aws)
![Page 24: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/24.jpg)
TWITTER IS NOT HATEOAS
RESTSEARCHSTREAM
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 apisaside: search can be modeled in HATEOAS, where POST is creation of search results, HEAD returns lifespan, etc
![Page 25: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/25.jpg)
api designed to parse quickly
simple extension (add new key)
consistent security model
AWS IS NOT REST AWS IS GOOD
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.
![Page 26: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/26.jpg)
WebSockets is not evenHTTP!
Handshake is HTTPishDiscoverable like ReST
Full-DuplexUncode or Binary MessagesTCP Protocol
Ex. 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
![Page 27: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/27.jpg)
Are consciously designed
Version at the right scope
Don’t leak implementation details
Use auth models relevant to consumer
Are well documented with examples
GOOD REST APIs
database details such as pagination, etc
![Page 28: IGOT99 PROBLEMS - files.meetup.com · COLLABORATE GROW ECOSYSTEM AND INNOVATE A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications](https://reader033.fdocuments.in/reader033/viewer/2022051808/600c15436b1e976fb712c6b2/html5/thumbnails/28.jpg)
➡join api-craft
➡read The REST API Design Handbook
➡read Web API Design eBook
➡socialize your ideas
What now?
Thank you!