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!