Video and slides synchronized, mp3 and slide download available at http://bit.ly/10iPQbf. Rickard Oberg explains how to expose use-cases to solve the linking problem in RESTful APIs, and how this will simplify both API development, documentation, as well as client development. Filmed at qconlondon.com. Rickard Oberg has worked on several OpenSource projects that involve J2EE development, such as JBoss, XDoclet and WebWork. He has also been Principal Architect of the SiteVision CMS/portal platform, where he used AOP as the foundation. Now he works for Neo Technology, building the leading graph database Neo4j. Twitter: @rickardoberg

1. One link at a time
Rickard Öberg, Neo Technology
QCon code: 7817
The Road to REST

2. InfoQ.com: News & Community Site
• 750,000 unique visitors/month
• Published in 4 languages (English, Chinese, Japanese and Brazilian
Portuguese)
• Post content from our QCon conferences
• News 15-20 / week
• Articles 3-4 / week
• Presentations (videos) 12-15 / week
• Interviews 2-3 / week
• Books 1 / month
Watch the video with slide
synchronization on InfoQ.com!
http://www.infoq.com/presentations
/REST-API-HATEOAS

3. Presented at QCon London
www.qconlondon.com
Purpose of QCon
- to empower software development by facilitating the spread of
knowledge and innovation
Strategy
- practitioner-driven conference designed for YOU: influencers of
change and innovation in your teams
- speakers and topics driving the evolution and innovation
- connecting and catalyzing the influencers and innovators
Highlights
- attended by more than 12,000 delegates since 2007
- held in 9 cities worldwide

4. How it all began

5. The Mission

6. A fork in the road
RMI?
SOAP?
REST?

7. Exploring

8. Richardson Maturity model
Level 0
SOAP, XML RPC, POX – Single URI
Level 1
URI Tunnelling – Many URIs, Single verb
Level 2
Many URIs, many verbs
CRUD services (e.g. Amazon S3)
Level 3
Level 2 + Hypermedia – RESTful Services

9. REST to the rescue!
“Representational State Transfer (REST)
is a style of software architecture for
distributed hypermedia systems such as
the World Wide Web”

10. Guidelines
Client–server
Stateless
Cacheable
Layered system
Uniform interface
http://en.wikipedia.org/wiki/Representational_State_Transfer#Constraints

11. More guidelines
Identification of resources
Manipulation of resources through
these representations
Self-descriptive messages
Hypermedia As The Engine Of
Application State (HATEOAS)

12. The narrow road

13. What shall we expose?
Client
Server
Data

14. What shall we expose?
Client
Server
Domain model

15. How?
Servlets?
JAX-RS?
Restlet
www.restlet.org

16. What the...?
/users/rickard/changepassword
/users/rickard/resetpassword

17. Where is HATEOAS?!?
“The next control state of an application resides
in the representation of the first requested
resource, … The application state is controlled and
stored by the user agent … anticipate changes to
that state (e.g., link maps and prefetching of
representations) … The model application is
therefore an engine that moves from one state to
the next by examining and choosing from
among the alternative state transitions in the
current set of representations.” - Roy Fielding

18. What now?!?

19. One step at a time

20. What shall we expose?
Client
Server
Use cases

21. From the user perspective
/account/changepassword
/administration/server/users/rickard/resetpassword

22. Who can do what?
/workspace/cases/<123>/
/administrator/...
/overview/...

23. Follow the named link
REST API
Links Link
Query Command

24. Application flow
GET ..../index
GET <link with rel="possiblelabels">
addlabel?id=1234, rel=addlabel,
"Urgent!"
POST the link

25. Link checking
What can the user do? Check for links!

26. Wohoo!

27. Versioning
HATEOAS helps
Exposing use cases helps
Send header
Ex. X-STREAMFLOW-API: 1.2
Client libraries

28. Performance
Exposing use cases really helps
Use e.g. GQL for table queries
Client decides columns and filtering
from fixed set

29. TL;DL
A Good REST API is like an ugly
website
RESTful clients should follow links
and submit forms

30. Q & A
rickard.oberg@neotechnology.com
@rickardoberg
http://rickardoberg.wordpress.com
http://qi4j.org