Review of Web, Query, and HATEOAS designs many call ReST. Motivations behind choices.

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

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

6. COLLABORATE
GROW
ECOSYSTEM
AND
INNOVATE

7. HOW
TO ReST SOAP
API

8. HOW
TO ReST WS-*
API

9. HOW
TO ReST ReST ish
API

10. HOW
TO not-soap HATEOAS
REST

11. To the
Level 0:
Level 1:
Swamp of POX
Resources
glory Level 2:
Level 3:
Verbs
Hypermedia
of
REST

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--

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

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

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. What makes
it HYPER?
➡Base Type
➡Links

17. abort
add
alternate
disk:attach
TRANSITIONS edit
remove
task
All transitions are discoverable via links

18. 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

19. Representing
HyperMedia
Extend Atom
Opaque + Link Headers
HAL
...

20. EXTEND ATOM
Vendor Type, Link elements
< 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--
domain-specific types
inherits link semantics from Atom

21. Link Headers
Opaque Type, Link elements
< HTTP/1.1 200 OK
< Content-Type: image/jpeg
Link: </images/foo.png>; rel="alternate"; type=”image/png”
010101010101010101
--snip--
supports binary types
facilitates intermediaries

22. Hypertext Application Language
Mix-in hypermedia controls into base type
embed resources for efficiency
< HTTP/1.1 200 OK
< Content-Type: application/hal+json
{
_links: {
self: {
href: '/example',
}
},
_embedded: {},
name: 'foo',
--snip--
domain-specific type agnostic

23. ELEGENT
clients always
know transitions
self-documenting
LETS USE
and discoverable
version at
HATEOAS
media-type
granularity

24. Perceived
Complexity?

25. Level 2
optimizes
for Coarse Grained Versions
CRUD++
Limited Representations
Today’s Tools
Simplicity over Elegance

26. IS IT ALL
JUST
PRICKLES
& GOO?

27. can we have both?

28. There Domain Style
Base Format
is no State Transfer
Level2 App Flow
Design
plus stuff like errors

29. REST Design
tools
➡Apiary
➡Swagger
➡iodocs

30. GOOD API DESIGNERS
UNDERSTAND
how it is used, and who will use it
importance of iterations and feedback
impacts to design beyond development
there’s no golden hammer (not even mongo)

31. TWITTER IS NOT
HATEOAS
REST
SEARCH
STREAM

32. AWS IS NOT REST
AWS IS GOOD
api designed to parse quickly
simple extension (add new key)
consistent security model
bulk ops

33. WebSockets
ain’t even
HTTP! Handshake is HTTPish
Discoverable like ReST
Full-Duplex
Uncode or Binary Messages
TCP Protocol

34. 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

35. What now?
➡join api-craft
➡read The REST API Design Handbook
➡read Building Hypermedia APIs...
➡socialize your ideas
Thank you!