This document discusses building RESTful APIs with the Play! web framework. It provides an overview of REST principles, introduces the Play! framework, and gives an example of building a RESTful blog API with Play! that follows Richardson maturity levels and uses routes, controllers, actions, and JSON.

1. Play! with REST
RESTful Web Services with Play!

2. About
● R&D Engineer at fluidOps
● Experiences with Play!
○ Version 1.4: Little custom made survey tool
○ Version 2.x: Distributed glossary at Capgemini
● Experiences with REST
○ Distributed Glossary exposed a REST interface
○ Played a little with Jersey (cf. JAX-RS)
http://github.com/gtrefs

3. This talk is about
● REST
○ What is REST?
○ What is a RESTful API?
○ Examples
● Play!
○ What is Play! ?
○ How do I built RESTful APIs with Play?
○ Example

4. REST
Representational State Transfer

5. Your experience?
● Experiences with REST
○ What is REST?
○ Who of you used REST?

6. Basic idea of REST
● Representational State Transfer
Network of web pages
(Application)
User User
Network of web pages
(Application)
Selects link
User
Network of web pages
(Application)
Representation of state

7. REST
● Term coined by Roy Fielding
● Architectural style
○ reflecting design decision and experiences while
adapting HTTP for the world wide web
○ constraints to emphasize specific properties
■ Client-Server → Scalability, Stateless (Session state kept
at client) → Scalability & Reliability, Uniform interface →
Independence of components, Use of Caching →
Efficiency, ...

8. The World Wide Web is
based on REST

9. REST APIs
APIs for the web

10. Richardson Maturity Model
● By Leonard Richardson
● 4 Levels of REST APIs
○ Level 0: HTTP as tunnel (cf. RPC)
○ Level 1: Resources
○ Level 2: HTTP verbs
○ Level 3: Hypermedia controls (aka HATEOAS)

11. Level 0 - HTTP as Transport Protocol
● Example: JSON-RPC
○ Relies on HTTP POST
○ Single service endpoint
http://blog.com/api
POST: {"jsonrpc": "2.0", "method": "create",
"params": ["Test", "message"], "id": 1}
200: {"jsonrpc": "2.0", "result": 0, "id": 1}
http://blog.com/api
POST: {"jsonrpc": "2.0", "method": "get",
"params": 0, "id": 2}
200: {"jsonrpc": "2.0", "result": ["Test",
"message"], "id": 2}

12. Level 1 - Resources
● Things which are addressable on their own
○ Entry collection: http://blog.com/api/entries
○ Single entry: http://blog.com/api/entries/{id}
http://blog.com/api/entries
POST: {"title":”Test”, "message":"message"}
200: {"id": 0}
http://blog.com/api/entries/0
POST
:
200: {"title":”Test”, "message":"message", "id":
0}

13. Level 2 - HTTP Verbs
http://blog.com/api/entries
POST: {"title":”Test”, "message":"message"}
201: Location: /api/entries/0
http://blog.com/api/entries/0
GET
200: {"title":”Test”, "message":"message", "id":
0}
● Exploit available semantics
○ GET: Retrieve information
○ DELETE: Remove resource
○ POST: New subordinate resource
○ PUT: Update or create resource

14. Level 3 - Hypermedia Controls
http://blog.com/api/entries
POST: {"title":”Test”, "message":"message"}
201: ... {"link":{"href": "/api/entries/0", "rel":"
item"}...}
http://blog.com/api/entries/0
GET
200: {"link":{"href":"/api/entries/0", "rel":"self"},
"link":{"href":"/api/entries", "rel":"collection"},
"title":”Test”, "message":"message", "id":0}
● Returned Hypermedia tells the client about
its interaction capabilities
○ Typed interlinking of resources (cf. Atom pub types)

15. Play! Web Framework
Based on Web MVC for Java and Scala

16. Your experience?
● Who knows what a Web Framework is?
● Who of you used a Web Framework?
○ RoR, Grails, Spring MVC, Zend or even Play!?

17. Basic workflow of Play!
routes
Client
HTTP Request
Controller/Action
Match
GET /api/entries
controller.Entries.list
HTTP Request
Model
models.Entry
View
views.html.Entry.list
Netty
SBT
JVM JacksonJPA
eBeanJava
Scala
Bean
Validation
Web
Sockets
Comet
Sockets
Akka
Twirl
JUnit
Mockito

18. Play!
● 2009: Released by Guillaume Bort
● Built on Akka
○ Part of the reactive Typesafe stack
○ Asynchronous and Non-blocking I/O
● Developer friendly
○ Does not hide HTTP
○ Web MVC
○ Everything is compiled

19. The Blog API
Play with entries

20. Building the Blog API
Resource Route Method Action
entries /blog/entries GET Retrieve all entries in the entries
collection
entries /blog/entries POST Create new entry from the payload
as item of the entries collection
entry /blog/entries/{id} GET Retrieve single entry for given id
entry /blog/entries/{id} PUT Update entry identified by given id
with information contained in the
payload
entry /blog/entries/{id} DELETE Delete entry from entries collection

21. The routes file
● Maps from request paths to actions
○ Path components can be declared as action
parameters

22. The Entries controller
● Logical container for all actions related to
entries
○ An action is a function which maps a request to a
response
○ Implementation of the Blog API

23. Get all entries action
● Retrieves all entries in the database
○ Uses JsonLinker to map entries to JSON

24. Create new entry action
● Creates new entry from HTTP body
○ Uses JSON BodyParser
○ Uses JsonLinker to return new entity as JSON

25. Get single entry action
● Retrieves a single entry for given id
○ Uses JsonLinker to map entry to JSON

26. Update single entry action
● Update single entry identified by given id
○ Uses JSON BodyParser

27. Delete single entry action
● Delete single entry identified by given id

28. Action composition
Code composition for Exception Handling, Authentication, …

29. Exception Handling
Calls Exception Result

30. Action composition
● In Play Scala actions are case classes
○ can be used in a functional style
○ wrap around other actions
● In Play Java: Annotation creep

31. Thank you! Questions?

32. REST Resources
● Richardson Marturity Model http://martinfowler.
com/articles/richardsonMaturityModel.html
● Discussion about the govdata.de API http://olivergierke.
de/2013/02/websites-vs-apis/
● Refactoring the govdata.de API https://speakerdeck.
com/owolf/turning-passive-apis-into-active-apis
● HAL https://tools.ietf.org/html/draft-kelly-json-hal-06

33. Play Resources
● Web Page https://www.playframework.com/
● GitHub https://github.
com/playframework/playframework