Play! with RESTRESTful Web Services with Play!

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

REST

Representational State Transfer

Your experience?

● Experiences with REST○ What is REST?○ Who of you used REST?

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

The World Wide Web is based on REST

REST APIs

APIs for the web

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)

Play! Web Framework

Based on Web MVC for Java and Scala

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

The Blog API

Play with entries

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

Update single entry action

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

Delete single entry action

● Delete single entry identified by given id

Action composition

Code composition for Exception Handling, Authentication, …

Exception Handling

Calls Exception Result

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

Thank you! Questions?

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