WHY WE API photo copyright 2005 Sony PicturesNow that we are here, we underscore motivations to even bother with.
COLLABORATE GROW ECOSYSTEM AND INNOVATEA Web API Study: Hurwitz;leads to integration -> stronger ecosystem -> more value > devices and applications in the ecosystem
HOW TO ReST SOAP APIAt ﬁrst glance, we might think how to present an api is rest vs soap
HOW TO ReST WS-* APIit might really be the aspects of WS-* that would make such a decision, such as WS-Security,AtomicTransaction, ReliableMessaging
HOW TO ReST ReST ish APISay we chose, ReST.. the thing is that ReST means a lot to many people
HOW TO not-soap HATEOAS RESTends up being something between soap and hypertext driven
To the Level 0: Level 1: Swamp of POX Resources glory Level 2: Level 3: Verbs Hypermedia of RESTLeonard Richardson circa 2008 Maturity Model
> 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"> same endpoint as XML <i href="#id1"/> --snip--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 method Side-effects are API-speciﬁcmany uris, but a single invocation method. operations might be encoded in parameters, andresource might be mixed in with them
VERBS > HEAD https://mybucket.s3.amazonaws.com/ 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 identiﬁed by the href
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 transitionundeﬁned in links
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 ﬁelds/linksSource: Dan Feist
ELEGENTclients alwaysknow transitionsself-documenting LETS USEand discoverableversion at HATEOASmedia-typegranularity
Perceived Complexity?sometimes domain models are well deﬁned, so the added value may be lost on the user
Level 2 optimizes for Coarse Grained Versions CRUD++ Limited Representations Today’s Tools Simplicity over EleganceLeonard 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, canyou persuade devs to adopt something they don’t want?
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)
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
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 classiﬁcations, 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.
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
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
What now? ➡join api-craft ➡read The REST API Design Handbook ➡read Web API Design eBook ➡socialize your ideas Thank you!