Put your client and server to rest - Javaone

Put your client and server to
REST with JAX-RS
Guilherme Silveira and Jan Algermissen

Guilherme Silveira
Technical leader, Instructor
@guilhermecaelum
guilherme.silveira@caelum.com.br

2002 guj.com.br
2003 vraptor
2004 caelumobjects.com
xp, xstream
Guilherme Silveira 2006 scrum
@guilhermecaelum
2009 restfulie, lean

Training and Consulting

Guilherme Silveira
@guilhermecaelum

a ge
o Im
y -N
rr
So 2002 Discovered REST
2005 1st pure REST project
2008 REST gaining momentum
Jan Algermissen
algermissen@acm.org 2009 NORD SC
@algermissen

bank.com calendar.com

travel.com company.com

what is the future
of integration
over the web?

Restful Web

Services

Restful Web

create a saas account

Services

Restful Web


freeze account
Services

Restful Web


freeze account
Services

reactivate account

Web

Restful Services

Web
http

Restful Services

Web
http

port 80

Restful Services

Web
http

port 80

ﬁrewall heaven

Restful Services

Web Services

xml, json
Restful

Web Services

xml, json
Restful
get, post, ...

Restful Web Services
as of 2009

But what about Hypermidia?
What about consumers?

Restful Web Services
as of 2009

But what about Hypermidia?
What about consumers?
There is much more!

unresttrips.com: ﬂight details

<?xml version="1.0" encoding="UTF-8" standalum="yes"?>
<flight>
<information>
<from>sao paulo</from>
<to>seoul</to>
</information>
<value>900.00</value>
</flight>

service locator when integrating:
coupling++

unrest
pay

unresttrips

guilherme

resttrips.com: ﬂight details

<flight>
<information>
<to>seoul</to>
</information>
<link rel="payment"
href="http://resttrips.com/payment/custom"/
</flight>

resttrips.com: making the payment

flight = Client.at('http://resttrips.com/f/574XR4').get();

confirmation = flight.getLink("payment").
patch(cardInformation, value);

resttrips.com: changing its payment provider

<flight>
<information>
<to>seoul</to>
</information>
<link rel="payment"
href="http://paysite.com/custom"/>
</flight>

dependency injection when integrating:

coupling--

restrips
pay

resttrips.com

guilherme

paysite.com

trip = resource
http://kayak.com/f/574XR4

payment = resource
any_uri_unknown_at_compile_time

resttrips.com: sharing a trip


patch(cardInformation, value/2);

// send the payment link to another part of the web


patch(cardInformation, value/2);

calendar: integrating my systems

myself = Client.at('http://users.calendar.com')
.with(auth).get();

myself.link("calendar").patch(flight.link("self"));

calendar: more examples

me.link("calendar").patch(link_to_birthday_list)
me.link("calendar").patch(link_to_hotel_reservation)
me.link("calendar").patch(link_to_trip_details)

so what?

Any update on the flight ==> reflects here
Any update on the hotel ==> reflects here
Any update on the meeting ==> reflects here

so what?

r at e!
i nt eg
us e,
ju st
o n ’t
d
Any update on the flight ==> reflects here
Any update on the hotel ==> reflects here
Any update on the meeting ==> reflects here

so what? that was just keeping an URI.


Remove ==> Cancels the flight
Remove ==> Cancels the reservation
Remove ==> Emails your coworkers


ro l!
co nt
a li ze
en tr
no tc
do

integration over the web

INTEGRATION is DECENTRALIZING the CONTROL
delegating to multiple agents
distributed systems

does our ‘rest’
sites in 2010 work
this way?


a t?
fo rm
hi ch
bu tw


too easy, right? who is that little girl?

too easy, right? who is that little girl?

ht er
da ug
y
notm
is
s he

content without
semantic has no value!

so what?

micro formats, media types, rdf etc

so what?

nk s!
er li
hyp
w ith
ats
fo rm
ic ro
m

micro formats, media types, rdf etc

Put your server to REST
leonard richardsons model

Server Maturity
1 uri, 1 http verb

/services.do?action=install&...

Server Maturity
1 uri, 1 http verb


@Path("/services")
public class Services {

  @GET
  public Response services(
    @QueryParam("action") String action) {

    ServiceFactory factory = new ServiceFactory();
    Service service = factory.getServiceFor(action);
    return service.execute();
  }

}

Server Maturity
1 uri, 1 http verb

public class InstallService {

  public Response execute() {
    return Response.ok()
             .type("application/xml")
             .entity("<service>...</service>")
             .build();
  }

}

1 uri, 1 http verb


I know them all beforehand.

1 uri, 1 http verb


Any change will break all our clients!

a priori knowledge
=
coupling++

Server Maturity
Multiple uris, 1 http verb

/install?...

Server Maturity
Multiple uris, 1 http verb

/install?...

@Path("/services")

  @GET @Path("install")
  public Response install() {
    return new InstallService().execute();
  }

  @GET @Path("uninstall")
  public Response uninstall() {
    return new UninstallService().execute();
  }

GET hell

GET should not imply in
undesireable effects

POST hell

GET could help us with
cache!

Server Maturity
Multiple uris, multiple verbs

POST /cloud
GET /cloud/1547437/software
POST /cloud/1547437/software

rails + restfulie
rubyonrails.org

rails + restfulie
rubyonrails.org
class SoftwaresController < ApplicationController

  acts_as_restfulie
  respond_to :xml, :json

  def create
    @item = Item.create(params[:item])
    respond_with @item, :status => :created
  end

  def show
    @item = Item.find(params[:id])
    respond_with @item
  end
end

Vraptor
vraptor.org/en
@Resource
public class SoftwareResource {

  public void install() {
    Software software = SoftwareRepository.register
(software);
    response.created(software);
  }

  public void uninstall() {
    response.deleted(software);
  }

}

JAX-RS

@Path("/softwares")

  @POST @Consumes("application/xml")
  public Response install(Software software) {
    software = SoftwareRepository.register(software);
    long id = software.getId();
    URI uri = UriBuilder.fromPath("/softwares/" + id)
                                       .build();
    software.install();
    return Response.created(uri).build();
  }

JAX-RS

  @DELETE @Path("{id}")
  public Response uninstall(@PathParam("id") Long id) {
    Software software = SoftwareRepository.retrieve(id);
    software.uninstall();
    return Response.ok().build();
  }

Uniform Interface++
Resources++

Http verbs example
POST creates

PUT replaces

PATCH updates

DELETE removes

GET retrieves

OPTIONS tells me what i can do

...

Is a Restful service
a cute CRUD?

hypermedia
enter amazon.com

search (GET)

hypermedia
enter amazon.com

search (GET)

create a payment (POST)

hypermedia
enter amazon.com

search (GET)

search (GET)


hypermedia
enter amazon.com

search (GET)

search (GET)

create a basket (POST)


hypermedia
enter amazon.com follow links

search (GET)

search (GET)



hypermedia
enter amazon.com follow links

search (GET)

search (GET)
ﬁll forms


Cloud API

GET /user/15 retrieves an user

Cloud API


follow GET machines accesses its machines

Cloud API



follow POST self installs a new machine

Cloud API



follow POST self installs a new machine

follow POST payment pay for it

retrieves an user

$ curl http://localhost:9998/user/574 -i
HTTP/1.1 200 OK
...

user

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user>
    <link rel="machines" href="/user/574/machines"/>
    <name>guilherme silveira</name>
    <website>www.caelum.com.br</site>
   <link rel="payment" href="/payment/custom"/>
    ...
</user>

maschine maschine maschine

$ curl http://localhost:9998/user/574/machines -i
HTTP/1.1 200 OK
Content-Type: application/xml

maschine
<machines xmlns:ns2="http://www.w3.org/2005/Atom">
  <machine>
    <ns2:link rel="self" href="/user/574/machines/1"/>
    <ns2:link rel="software" href="/machines1/softwares"/>
    <id>1</id>
    <host>www.caelum.com.br</host>
    <softwares>
      <software>
        <id>1234</id>
        <ns2:link rel="self" href="/softwares/1234"/>
      </software>
    </softwares>
  </machine>
</machines>

payment

<user>
    <link rel="machines" href="/user/574/machines"/>
    <name>guilherme silveira</name>
    <website>www.caelum.com.br</site>
   <link rel="payment" href="/payment/custom"/>
    ...
</user>

@XmlRootElement
@XmlType(propOrder= {"id", "host", "softwares", "links"})
public class Machine {
  private final all variables here;

  @XmlElement(name="link", namespace="http://www.w3.org/2005/Atom")
  public List<Link> getLinks() {
    return Arrays.asList(
      Link.to("/machines/" + getId(), "self"),
      Link.to("/machines/" + getId() + "/softwares", "softwares")
    );
  }

  @XmlElementWrapper(name="softwares")
  @XmlElement(name="software")
  public List<Software> getSoftwares() {
    return softwares;
  }

  public void install(Software software) {
    getSoftwares().add(software);
  }

  public void uninstall(Software software) {
    getSoftwares().remove(software);
  }

} Machine.java

@Path("/machines")
public class MachineResource { MachineResource
@Path("{id}/softwares")
public SoftwareResource softwares(@PathParam("id") Long id) {
Machine machine = new MachineRepository().retrieve(id);
if (machine != null) {
SoftwareResource softwareResource = new SoftwareResource();

softwareResource.setMachine(machine);
return softwareResource;
}
throw new WebApplicationException(404);

}


public Response create(Machine machine) {

Long id = new MachineRepository().save(machine);

return Response.created(UriBuilder.fromPath("/" + id).build()).build();

}

@GET @Path("{id}")

@Produces("application/xml")

public Machine show(@PathParam("id") Long id) {

return new MachineRepository().retrieve(id);

}

@GET

@Produces("application/xml")

public Machines list() {

Machines machines = new Machines();

machines.setMachine(new MachineRepository().list());

return machines;

Server Model
according to
Leonard Richardson, 2008

one uri + one verb

Server Model
according to

Ugly
one uri + one verb

Server Model
according to

multiple
uris

one uri + one verb

Server Model
according to

Less ugly
multiple
uris

one uri + one verb

Server Model
according to

multiple
verbs
multiple
uris

one uri + one verb

Server Model
according to
cute CRUD
multiple
verbs
multiple
uris

one uri + one verb

Server Model rest
according to
Leonard Richardson, 2008 hypermedia

multiple
verbs
multiple
uris

one uri + one verb

JAX-RS wishlist

VRaptor and Restfulie

1. conventions?

@Path("/services")

  @GET
  public Response services(
    @QueryParam("action") String action) {

    ServiceFactory factory = new ServiceFactory();
    Service service = factory.getServiceFor(action);
    return service.execute();
  }

}

Convention over Conﬁguration

@Resource

private final ServiceFactory factory;

public Services(ServiceFactory factory) {
this.factory = factory;
}

public void services(String action) {
factory.getServiceFor(action).execute();
}

}

do you want to avoid
copy+paste?

2. TDD: hard to test
@Path("/products")
public class Products {
coupled to the
  @GET implementation
  public Response create(
    @QueryParam("what") String what) {

    // persists
    return Response.ok()
             .type("application/xml")
             .entity("<product>...</product>")
             .build();
  }

}

TDD: mock it
coupled to the interface
couple--

@Resource

private final Response response;

public Services(Response response) {
this.response = response;
}

public void services(String action) {
response.getServiceFor(action).execute();
}

}

3. Content negotiation by hand

@Path("/softwares")

                                       .build();
software.install();
  }

Let us do it for you.

@Resource

@Post @Consumes
    response.created(software);
  }

}

4. URI coupling

writing the URI once

...

  @GET @Path("/softwares/{id}")
  public Response install(@QueryParam("id") Software
software) {
// ...
  }

4. URI coupling
writing the URI again
several times
@Path("/softwares")

                                       .build();
software.install();
  }

4. URI coupling
code
@Path("/softwares")

                                       .build();
software.install();
  }

ZERO uri replication

@Resource

@Post @Consumes
    // ...
    response.use(SoftwareResource.class).show(software);
  }

}

5. Parameter list

@Path("/machines")
public class MachineResource {

@Path("{id}/softwares")
public SoftwareResource softwares(@PathParam("id") Long id) {
Machine machine = new MachineRepository().retrieve(id);
if (machine == null) {
throw new WebApplicationException(404);
}
// ...

}

}

Yes, we can do it.

@Resource
public class MachineResource {

@Post ("{m.id}/softwares")
public SoftwareResource softwares(Machine m) {
Machine machine = new MachineRepository().retrieve(m
// ...

}

}

parameter converter chain of responsability

example
restfulie.caelumobjects.com

Response response = client.at
("http://localhost:9998/user/574").get();

6. Client internal DSLs

Response response = client.at
("http://localhost:9998/user/574").get();

User user = response.getResource();
System.out.println("user: " + user.getName());

6. Client internal DSLs

User user = response.getResource();
System.out.println("user: " + user.getName());

Link link = resource(user).getLink("machine");
response = link.follow().post(new Machine());

Link link = resource(user).getLink("machine");
response = link.follow().post(new Machine());

double amount = resource(user).refresh().
getAmountDue();

double amount = resource(user).refresh().
getAmountDue();

link = resource(user).getLink("payment");
Payment payment = new Payment(amount);
response = link.follow().post(payment);


System.out.println("payment completed");


System.out.println("payment completed");

i was looking for a DSL
and i did not know it!

Putting JAX-RS Clients to
REST

“Jersey View Client”

• Developed early 2010
• w/ Paul Sandoz (@paulsandoz)
• To-be Jersey RESTful client API
• Feedback welcome!

Goals

• Encourage RESTful client side programming
• Natural coding model
• Resemble JAX-RS annotation style

Web Browser Tasks
• GET resource after user enters URL

Web Browser Tasks
• Build up Web page

Web Browser Tasks
• Show informatin (title, content)

Web Browser Tasks
• Expose links and forms

Web Browser Tasks
• Expose links and forms
• Act upon link activation or form
submission

A Web Page
• Has a location
• Build from response(s)

A Web Page
• Has a location
• Holds application state

A Web Page
• Has a location
• Exposes application state

A Web Page
• Has a location
• Exposes links and forms

A Web Page
• Has a location
• Exposes links and forms
• Assumptions

User Agent

• Use entry URI to start application

User Agent

• Build up application state from response(s)

User Agent

• Make state available

User Agent

• Make hypermedia controls activatable

User Agent

• Make hypermedia controls activatable
• Construct request upon control activation

A View
• Bound to resource

A View

A View
• Enables activation of controls

A View
• Enables activation of controls
• Bundles Assumptions

View:
Combination of state
and assumptions,
bound to a URI

Browser:
A single kind of
view!

Can’t do machine REST
with a single kind of
view

Not just one kind of
application state

Atom Pub

• Service view
• Feed view
• Entry View

Our Example

• User account view
• Machine View
• Invoice View

Use classes to
represent kinds of
views

A view class for a Web Page View
WebPageView pageView = client.view(
“https://twitter.com/signup”,WebPageView.class);

Form form = page.getFormsByIndex(0);
form.name = “John”;
form.submit();

View Classes
• Relate instance to resource

View Classes
• Handle response

View Classes
• Handle response
• Build up application state

View Classes
• Handle response
• Expose application state

View Classes
• Handle response
• Expose hypermedia controls

View Classes
• Handle response
• Perform requests upon control activation

View Classes
• Handle response
• Perform requests upon control activation
• Bundle assumptions

A class for account views

URI ACCOUNT_URI = new URI(
“http://example.org/saas/user/john/account”);
Client client = new Client();

// Create view instance bound to a URI
AccountView av = client.view(ACCOUNT_URI, AccountView.class);

// Access application state held by view

// Invoke controls exposed by view

A Media Type
GET /saas/user/john/account

200 Ok
Content-Type: application/saas

<account>
<machines href=”./machines”
accept=”application/saas;type=machine”/>
<payments href=”./payments”
accept=”application/saas;type=payment”/>
<userData>
<name>John Doe</name>
...
</userData>
</account>

public class AccountView {
// hold state
private ViewResource machineCollection;
private ViewResource paymentProcessor;
private String userName;

@GET @Consumes(“application/saas;type=account”)
public void build(Account account) {
// build state from response
}

public String getUserName() { return userName; }

// <machines href=””/> control exposed
public CreatedMachineView addMachine(Machine machine) {
return machineCollection.post(machine,
CreatedMachineView.class)
}

// <payments href=””/> control exposed
public void submitPayment(Payment payment) {
paymentProcessor.post(payment);
}
}

Choosing a certain
view class to handle a
response manifests an
assumption!

Using View Classes
AccountView accountView = client.view(
ACCOUNT_URI,AccountView.class);
LOG.info(“Working on account for “ +
accountView.getUserName());

Machine machine = newMachine();
CreatedMachineView cmv = accountView.addMachine(machine);
LOG.info("New machine is at: " + cmv.getLocation());

InvoiceView invoiceView = cmv.getInvoiceView();
Payment payment = new Payment(invoiceView.getAmount(),
myCreditCardData);
accountView.makePayment(payment);

Things to Note
• Think of view like of browser window

Things to Note
• Can keep them around, go back, use any
time

Things to Note
time
• Handle for application state

Things to Note
time
• View class is single point of code

Things to Note
time
• Bundles code and expectations

Things to Note
time
• Bundles code and expectations
• Views classes used deﬁne application

Presentation Online

http://slidesha.re/put_them_to_rest

After-Talk Discussion

Come and discuss RESTfulie and Jersey View
Client.

In a world with serious
issues

What is the magical
solution?

sunday in the park

“Ah, yes, a similar thing happens all the time
when ﬂaying frisbee in the park with my dog.
When I throw the frisbee and the dog tries to
catch it in his teeth, everyone seems to be
happy.”

sunday in the park

“However, when the dog tries to throw the
frisbee and I try to catch it in my teeth,
it just doesn't seem to work well for either of
us.”

Roy Fielding, REST creator

If JMS does not ﬁt your
problem, do not try to ﬁt your
solution within JMS.

If SOA does not ﬁt your
solution within SOA.

If REST does not ﬁt your
solution within REST.

The golden rule

If * does not ﬁt
your problem,
do not try to ﬁt
your solution
within *.

code samples

Lucas Cavalcanti
(java server)
@lucascs

Anderson Leite (ruby)
@anderson_leite

Further reading
Roy Fielding dissertation

Further reading

Rest in Practice, Jim Webber and others

Further reading


Restful Webservices Cookbook, Subbu Allamaraju

Further reading



Restful Web Services, Richardson and Ruby

Further reading




JAX-RS speciﬁcation

Further reading





Infoq articles on REST

Further reading





Infoq articles on REST

Restfulie guide

Jersey related
Jersey related posts

Jersey related

http://www.nordsc.com/blog/?cat=28

Jersey related


Repository

Jersey related


Repository

https://jersey.dev.java.net/

Jersey related


Repository


Presentation

Jersey related


Repository


Presentation

http://www.nordsc.com/presentations/j1/

Interviews and
Presentations
Stefan Tilkov interview on InfoQ

Interviews and
Presentations

http://bit.ly/9RUXKL

Interviews and
Presentations


Leonard Richardson’s presentation at QCon

Interviews and
Presentations



http://bit.ly/dj2W66

Interviews and
Presentations




Martin Fowler on REST

Interviews and
Presentations




Martin Fowler on REST

http://bit.ly/bx61ci

Interviews and
Presentations
Ian Robinson and Jim Webber interview

Interviews and
Presentations

http://bit.ly/aEuzj3

Interviews and
Presentations


Jan Algermissen classiﬁcation

Interviews and
Presentations



http://bit.ly/cycFBF

Interviews and
Presentations




Guilherme Silveira on REST clients

Interviews and
Presentations




Guilherme Silveira on REST clients

http://bit.ly/aHCglv

code samples
JAX-RS

http://jcp.org/en/jsr/detail?id=311

code samples
JAX-RS


Rails

code samples
JAX-RS


Rails

http://rubyonrails.org

code samples
JAX-RS


Rails


Restfulie

code samples
JAX-RS


Rails


Restfulie

http://restfulie.caelumobjects.com

code samples
JAX-RS


Rails


Restfulie


VRaptor

code samples
JAX-RS


Rails


Restfulie


VRaptor

http://vraptor.org/en

Put your client and server to rest - Javaone

Recomendados

Recomendados

Mais conteúdo relacionado

Destaque

Destaque (20)

Semelhante a Put your client and server to rest - Javaone

Semelhante a Put your client and server to rest - Javaone (20)

Último

Último (20)

Put your client and server to rest - Javaone

Notas do Editor