igot99 problems - files.meetup.com · collaborate grow ecosystem and innovate a web api study:...
TRANSCRIPT
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
➡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
๏@adrianfcole
๏architect CloudHub at MuleSoft
๏founder jclouds
WHO IS THIS GUY?
THANKS★ api-craft
★ mattstep
★ gtcampbell
★ mulies
photo copyright 2005 Sony Pictures
WHY WE API
Now that we are here, we underscore motivations to even bother with.
COLLABORATEGROW ECOSYSTEMAND INNOVATE
A Web API Study: Hurwitz; leads to integration -> stronger ecosystem -> more value > devices and applications in the ecosystem
HOW TO API
ReST SOAP
At first glance, we might think how to present an api is rest vs soap
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
HOW TO API
ReST ReSTish
Say we chose, ReST.. the thing is that ReST means a lot to many people
HOW TO REST
HATEOASnot-soap
ends up being something between soap and hypertext driven
To the glory of REST
Level 0: Swamp of POXLevel 1: ResourcesLevel 2: VerbsLevel 3: Hypermedia
Leonard Richardson circa 2008 Maturity Model
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
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
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
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--
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
➡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
LETS USEHATEOAS
clients always know transitions
self-documenting and discoverable
version at media-type granularity
ELEGENT
Perceived Complexity?
sometimes domain models are well defined, so the added value may be lost on the user
Level 2 optimizes for Coarse Grained Versions
CRUD++Limited RepresentationsToday’s ToolsSimplicity over Elegance
Leonard Richardson circa 2008 Maturity Model
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?
KNOW What you need
Who its for
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)
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
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.
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
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
➡join api-craft
➡read The REST API Design Handbook
➡read Web API Design eBook
➡socialize your ideas
What now?
Thank you!