restful groovy

RESTful GroovyImplementing JAX-RS with Groovy

Contact Info

Ken Kousenken.kousen@kousenit.com@kenkousen

Making Java Groovyhttp://manning.com/kousen

REST

Term from Ph.D. thesis by Roy FieldingCo-founder Apache HTTP Server projectPart of IETF working groups for:

URI, HTTP, HTML

Architectural Styles and the Design ofNetwork-based Software Architectures

REST

Representational State Transfer

- Addressable resources- Uniform interface- Content negotiation- Stateless services

Addressable Resources

Use URLs to access items(no verbs in URLs)

Uniform Interface

HTTP verbsGET

POST

PUT

DELETE

---- HEAD

OPTIONS

PATCH

Safe vs Idempotent

Safe → no server side changesGET

Idempotent

Idempotent requests can be repeatedNo additional effects

GETPUTDELETE

Http Status Codes

200s → good200 OK, 201 created, 204 no content

300s → moved400s → you messed up

404 not found, 409 conflict(see 418, 420 for fun)

500s → we messed up

RESTful service

ImplementationsGET → retrieve dataPOST → insert data

set Location header for new itemPUT → update dataDELETE → remove data

RESTful service

Yes, that’s a URL-driven database

RESTful service

Yes, that’s a URL-driven database

(Hypermedia advocates are squirming,but we’ll get there)

Content Negotiation

Client can request representations

Usually via MIME typein Accept header

Stateless Services

No state maintained in service

All interactions via self-contained requests

HATEOAS

HypermediaAsTheEngineOfApplicationState

An unpronounceable acronymwith the word HATE in it

Hypermedia

Goal is true decouplingClient asks for first URLResponse includes links

Works like the web, but programmatically

The Java Approach

JAX-RS 1.1Implements JSR 311 spec

JAX-RS 2.0Implements JSR 339 spec

JAX-RS

ImplementationsJersey (R.I.)RestEasyRestletsRestfulieApache CXF

JAX-RS

Note: Spring REST annotationsdo NOT implement JAX-RS

POGO

Resources are POGOs

Representations are based onMIME-types

Hypermedia comes from links and annotations

Server Side

JAX-RS

Annotations@GET, @POST, @PUT, @DELETE

@Produces, @Consumes

@Path, @PathParam

@Context

JAX-RS

Classes, interfaces, enumsResponse

Response.ResponseBuilder

UriInfo

UriBuilder

MediaType

Client Side

HttpBuilder projectwraps Apache HTTP Clienthttp://groovy.codehaus.org/modules/http-builder/

Source code:https://github.com/jgritman/httpbuilder

Client Side

JAX-RS 2.0 includes client libraryClientBuilder

WebTarget

Hypermedia

Hypermedia

Trivia

Did you know?

Neither the word “hypermedia” nor HATEOASappear anywhere in the JSR 399 specification

(No, I don’t know why either)

Links

Adding transitional linksResponse.ResponseBuilder

link (several overloads)links

Link class

Links

Adding structural linksUse Link attributes inside POGOAdd JAXB annotations

@XmlJavaTypeAdapter(JaxbAdapter)

Links

Customizing links

Groovy API: JsonBuilder

JsonSlurper

Use a custom JAX-RS provider

Custom Provider

Implement:MessageBodyReader<T>

MessageBodyWriter<T>

Summary

JAX-RS 2.0 specificationJersey reference implementation

Hypermedia done through links

Groovy simplifies codeNo major changes unless custom providerHttpBuilder client