Download - Play! with rest
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
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
Basic idea of REST
● Representational State TransferNetwork of web pages
(Application)
User User
Network of web pages(Application)
Selects link
User
Network of web pages(Application)
Representation of state
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, ...
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)
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}
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}
Level 2 - HTTP Verbs
http://blog.com/api/entriesPOST: {"title":”Test”, "message":"message"}
201: Location: /api/entries/0
http://blog.com/api/entries/0GET
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
Level 3 - Hypermedia Controls
http://blog.com/api/entriesPOST: {"title":”Test”, "message":"message"}
201: ... {"link":{"href": "/api/entries/0", "rel":"item"}...}
http://blog.com/api/entries/0GET
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)
Your experience?
● Who knows what a Web Framework is?● Who of you used a Web Framework?
○ RoR, Grails, Spring MVC, Zend or even Play!?
Basic workflow of Play!
routes
Client
HTTP Request
Controller/Action
Match
GET /api/entries
controller.Entries.list
HTTP Request
Model
models.Entry
Viewviews.html.Entry.list
Netty
SBT
JVM JacksonJPA
eBeanJava
Scala Bean Validation
Web Sockets
Comet Sockets
Akka
Twirl
JUnit
Mockito
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
Building the Blog APIResource 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
The routes file
● Maps from request paths to actions○ Path components can be declared as action
parameters
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
Get all entries action
● Retrieves all entries in the database○ Uses JsonLinker to map entries to JSON
Create new entry action
● Creates new entry from HTTP body○ Uses JSON BodyParser○ Uses JsonLinker to return new entity as JSON
Get single entry action
● Retrieves a single entry for given id○ Uses JsonLinker to map entry to JSON
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
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
Play Resources
● Web Page https://www.playframework.com/ ● GitHub https://github.
com/playframework/playframework