Rest

REST with JAX-RS,
Security, Java EE 6

Carol McDonald

Agenda
• REST Primer
• RESTful Design and API Elements
• Building a Simple Service
• Security
• Q&A

REpresentational State Transfer

Get Response XML data =
REST Web
http://www.depot.com/parts
Service REpresentational State

Client Transfer Client
State1 State2

 The URL identifies the resource
 Click on the url (resource) in page (hypermedia)
html page is transferred to the browser
REpresentational State transfer occurs

REST Tenets

• Resources (nouns)
> Identified by a URI, For example:
 http://www.parts-depot.com/parts

• Methods (verbs) to manipulate the nouns
> Small fixed set:
 GET, PUT, POST, DELETE
Read, Update, Create, Delete
• Representation of the Resource
> data and state transferred between client and server
> XML, JSON...

• Use verbs to exchange application state and
representation

method resource
Request: GET http://localhost:8080/RestfulCustomer/webresources/model.customer/1

Status: 200 (OK)

Time-Stamp: Fri, 14 Dec 2012 02:19:34 GMT

Received:
{"name":"Jumbo Eagle Corp","state":"FL","customerId":1,
"addressline1":"111 E. Las Olivas Blvd","addressline2":"Suite 51",
"city":"Fort Lauderdale","phone":"305-555-0188","fax":"305-555-0189",
"email":"jumboeagle@example.com","creditLimit":100000
}

representation

Rest Uniform Interface:
Every thing is a Resource

Every resource has an id, URI is the id
 http://company.com/customers/123456

Every Resource has an Id

URI is the id, Every resource has a URI

http://company.com/customers/123456

Resource Collection name
Primary key
• URIs identify :
> items, collections of items, virtual and physical objects, or computation results.

http://company.com/customers/123456/orders/12
http://example.com/orders/2007/11
http://example.com/products?color=green

Rest Standard Interface:
Use Standard HTTP Methods
• Example
 GET /store/customers/123456

Use Standard Methods:
• /orders
– GET - list all orders Order Customer
– POST - submit a new order Mgmt Example
 /orders/{order-id}
> GET - get an order representation
> PUT - update an order
> DELETE - cancel an order
 /orders/average-sale
– GET - calculate average sale
• /customers http://www.infoq.com/articles/rest-
– GET - list all customers introduction
– POST - create a new customer
 /customers/{cust-id}
> GET - get a customer representation
> DELETE- remove a customer
 /customers/{cust-id}/orders
– GET - get the orders of a customer

Use Standard HTTP Methods

• HTTP Get, Head
> Should not modify anything
> Cache-able
With Correct use of Last-Modified and
ETag
• Idempotency:
> PUT, DELETE, GET, HEAD can be repeated
and the results are the same

Link things together
• Hypermedia
• As
• The
• Engine
• Of
• Application
• State
HATEOAS

© Availity, LLC | All rights reserved.

Link Things Together

Representations contain links to other resources:
<prop self="http://example.com/orders/101230">
<customer ref="http://example.com/customers/bar">
<product ref="http://example.com/products/21034"/>
<amount value="1"/>
</order>

• Service provides links in response to the Client
> Enables client to move the application from
one state to the next by following a link

Example

http://www.infoq.com/articles/webber-rest-workflow

Example


Multiple Representations

• Offer data in a variety of formats, for different needs
> XML
> JSON
> (X)HTML

• Support content negotiation
> Accept header
GET /foo
Accept: application/json
> URI-based
GET /foo.json

> Response header
> Content-Type application/xml

content negotiation
Request: http://localhost:8080/RestfulCustomer/webresources/application.wadl

Status: 200 (OK)

Time-Stamp: Fri, 14 Dec 2012 03:11:50 GMT

Received:

<?xml version="1.0" encoding="UTF-8"?>
<resources base="http://localhost:8080/RestfulCustomer/webresources/">
<resource path="model.customer">
<method id="findAll" name="GET">
<response>
<representation mediaType="application/xml"/>
<representation mediaType="application/json"/>
</response>
</method>

Stateless Communications

• HTTP protocol is stateless
• Everything required to process a request contained in the
request
> No client session on the server
> Eliminates many failure conditions

• application state kept on Client
• Service responsible for resource state

Rest Common Patterns: Container, Item
Server in control of URI
• Container – a collection of items
• List catalog items: GET /catalog/items
• Add item to container: POST /catalog/items
> with item in request
> URI of item returned in HTTP response header
> e.g. http://host/catalog/items/1

• Update item: PUT /catalog/items/1
> with updated item in request

Good example: Atom Publishing Protocol

Common Patterns: Map, Key, Value
Client in control of URI

• List key-value pairs: GET /map
• Put new value to map: PUT /map/{key}
> with entry in request
> e.g. PUT /map/dir/contents.xml

• Read value: GET /map/{key}
• Update value: PUT /map/{key}
> with updated value in request
• Remove value: DELETE /map/{key}

• Good example: Amazon S3

Rest Key Benefits
• Server side
> Uniform Interface
> Cacheable
> Scalable
> Easy failover

• Client side
> Easy to experiment in browser
> Broad programming language support
> Choice of data formats

Agenda
• REST Primer
• RESTful Design and API Elements with JAX-RS
• Status
• Q&A

JAX-RS: Clear mapping to REST concepts

• High level, Declarative
> Uses @ annotation in POJOs
• Jersey – reference implementation of JSR 311
 Download it from http://jersey.dev.java.net
 Comes with Glassfish, Java EE 6
 Tools support in NetBeans

Resources

• Resource class
> POJO, No required interfaces
• ID provided by @Path annotation
> Relative to deployment context
> Annotate class or “sub-resource locator” method

http://host/ctx/orders/12
@Path("orders/{id}")
public class OrderResource {
@Path("customer")
http://host/ctx/orders/12/customer
CustomerResource getCustomer(...) {...}
}

Request Mapping
• Annotate resource class methods with standard method
> @GET, @PUT, @POST, @DELETE, @HEAD
• annotations on parameters specify mapping from request data
• Return value mapped to http response

@Path("orders/{order_id}")
public class OrderResource {
@GET
Order getOrder(@PathParam("order_id") String id) {
...
}
}

Static and dynamic content negotiation

• Annotate methods or classes
> @Produces matches Accepts header
> @Consumes matches Content-Type
header
@GET
@Consumes("application/json")
@Produces({"application/xml","application/json"})
String getOrder(@PathParam("order_id") String id) {
...
}

Multiple Representations: JAX-RS
consuming

@Path("/items/")
@ConsumeMime(“application/xml”)
public class ItemsResource {
http://host/catalog/items/?start=0
@GET
ItemsConverter get(@QueryParam("start")
int start) {
...
} http://host/catalog/items/123
@Path("{id}/")
ItemResource getItemResource(@PathParam("id")Long id){
...
}
}


@Post
@ConsumeMime(“application/x-www-form-urlencoded”)
@ProduceMime(“application/xml”)

public JAXBClass updateEmployee(
MultivalueMap<String, String> form) {

...

converted to XML Converted to a map for
accessing form's field

Multiple Representations: producing a
response
@Path(“/items”)
class Items {
Use Response class
to build “created”response
@POST
@ProduceMime(“application/xml”)
Response create(Ent e) {
// persist the new entry, create URI
return Response.created(
uriInfo.getAbsolutePath().
resolve(uri+"/")).build();
}
}

Uniform interface: HTTP request and response

C: POST /items HTTP/1.1
C: Host: host.com
C: Content-Type: application/xml
C: Content-Length: 35
C:
C: <item><name>dog</name></item>
S: HTTP/1.1 201 Created
S: Location: http://host.com/employees/1234
S: Content-Length: 0

Link Things Together
• UriInfo provides information about the request URI and the
route to the resource
• UriBuilder provides facilities to easily build URIs for
resources

@Context UriInfo info;
OrderResource r = ...
UriBuilder b = info.getBaseUriBuilder();
URI u = b.path(OrderResource.class).build(r.id);

Agenda
• REST Primer
• RESTful Design and API Elements
• Deployment Options
• Status

URIs and Methods:
Item Catalog Example
 /items
– GET - list all items
– POST – add item to catalog
 /items/{id}
> GET - get an item representation
> PUT - update an item
> DELETE – remove an item

http://www.infoq.com/articles/rest-
introduction

Methods
@Path(“/items”)
class ItemsResource {
@GET
public List<Item> findAll() { ... }
@POST Response create(Item) { ... }
@PUT
@Path("{id}")
public void editp(Item entity) {}
@GET
@Path("{id}")
public Item find(@PathParam("id")
Integer id) { ... }
}
Java method name is not significant
The @HTTP method is the method

RESTful Catalog

 Javascript client, JAX-RS, JSON, JPA
Registration Application
JAX-RS class Entity Class
JSON class
Item DB

ItemsResource

javascript client

Item Entity JAXB annotated
@Entity
@Table(name = "ITEM")
@XmlRootElement
public class Item implements Serializable {
@Id
private Integer id;
...
}

XML
<item uri="http://localhost/Web/resources/items/1/">
<description> black cat is nice</description>
<id>1</id>
<imagethumburl>/images/anth.jpg</imagethumburl>
<name>not Friendly Cat</name>
<price>307.10</price>
<productid>feline01</productid>
</item>

JSON

{
"@uri":"http://host/catalog/resources/items/1/",
"name":"Friendly Cat",
"description":"This black and white colored cat is super friendly.",
"id":"1",

"imageurl":"http://localhost:8080/CatalogService/images/anthony.jpg"
}

Resource Classes

> Items Resource retrieves updates a collection of Item
entities
> /items – URI for a list of Items
> /item/1 – URI for item 1

JAX-RS class Entity Class

Item DB

ItemsResource

Dojo client

Get Items
responds to the URI http://host/catalog/items/

@Path("/items/") responds to HTTP GET
public class ItemsResource {
responds with JSON
@GET
@Produces("application/json") JAXB class
public List<Item> get(){
CriteriaQuery cq = getEntityManager().
getCriteriaBuilder().createQuery();
cq.select(cq.from(Item));
return getEntityManager().createQuery
(cq).getResultList();
}
Performs JPA
Query, returns list
of entities

JQuery Client
var rootURL = "http://localhost:8080/catalog/resources/item";
// Retrieve item list
function findAll() {
$.ajax({
type: 'GET',
url: rootURL,
dataType: "json",
success: renderList });
}
function renderList(data) {
var list =data;
$('#itemList li').remove();
$.each(list, function(index, item) {
$('#itemList').append('<li><a href="#" data-identity="' + item.id + '">'+item.name+'</a></li>');
});
}

Backbone.js client


MVC


Backbone.sync maps CRUD requests to REST
Save (new) → create → HTTP POST /url
Fetch → read → GET /url/id
Save → update → PUT /url/id
Destroy → delete → DELETE /url/id


backbone Client
window.Item = Backbone.Model.extend({
urlRoot: "resources/items",
defaults: {
id: null,
name: "",
description: "",
imageurl: null
}
});

window.ItemCollection = Backbone.Collection.extend({
model: Item,
url: "resources/items"
});

Securing your REST Web Service

• Authentication for Identity Verification
• Authorizaton
• Encryption

Authentication: Configure web.xml
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>admin</realm-name>
</login-config>

<login-config>
<auth-method>BASIC</auth-method>
<realm-name>admin</realm-name>
</login-config>
• Login-config:
> defines how HTTP requests should be
authenticated
• Auth-method:
> BASIC, DIGEST, or CLIENT_CERT. corresponds
to Basic, Digest, and Client Certificate
authentication, respectively.
• Realm-name: realm
> Name for database of users and groups that
identify valid users of a web application

<security-constraint>
<web-resource-collection>
<url-pattern>/secure/*</url-pattern>
<http-method>POST</http-method>
</web-resource-collection>
...

• security constraint
> defines access privileges to a collection of
resources
• url-pattern:
> URL pattern you want to secure
• Http-method:
> Methods to be protected

...
<auth-constraint>
<description>only let admin login </description>
<role-name>admin</role-name>
</auth-constraint>

• auth-constraint:
> names the roles authorized to access the URL
patterns and HTTP methods declared by this
security constraint

Encryption: Configure web.xml
...
<user-data-constraint>
<description>SSL</description>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>

• user-data-constraint: NONE, INTEGRAL, or
CONFIDENTIAL
> how the data will be transported between client
and server


<security-role>
</security-role>

• security-role:
lists all of the security roles used in the application
> For every <role-name> used in <auth-
constraints> must define a corresponding
<security-role>
• http://java.sun.com/javaee/5/docs/tutorial/doc/bncas.html

Authentication: map roles to realm
<sun-web-app>
<security-role-mapping>
<principal-name>admin</principal-name>
</security-role-mapping>
</sun-web-app>
LDAP
• security-role-mapping: realm
> Assigns security role to a group or user in
Application Server realm
• Realm:
> database of users and groups that identify valid
users of a web application (FILE, LDAP

Authentication: map roles to realm
file
realm

Authorization Annotations
roles permitted to execute operation
@Path("/customers")
@RolesAllowed({"ADMIN", "CUSTOMER"})
public class CustomerResource {
@GET
@Path("{id}")
@Produces("application/xml")
public Customer getCustomer(@PathParam("id")
int id) {...}
@RolesAllowed("ADMIN")
@POST
@Consumes("application/xml")
public void createCustomer(Customer cust) {...}
@PermitAll
@GET
@Produces("application/xml") authenticated user
any
public Customer[] getCustomers() {}
}

JAX-RS Security Context

public interface SecurityContext {
Determine the identity of the user
public Principal getUserPrincipal();
check whether user belongs to a certain role
public boolean isUserInRole(String role);
whether this request was made using a secure channel
public boolean isSecure();
public String getAuthenticationScheme();
}

JAX-RS Security Context

@Path("/customers") check whether user
public class CustomerService { belongs to a certain role
@GET
@Produces("application/xml")
public Customer[] getCustomers(@Context
SecurityContext sec) {
if (sec.isSecure() && !sec.isUserInRole("ADMIN")){
logger.log(sec.getUserPrincipal() +
" accessed customer database.");
}
...
}
}
Determine the identity of the user

Java EE 6

• JAX-RS is part of Java EE 6
• Gradle dependencies are easy

apply plugin: 'war'
dependencies {
testCompile 'org.glassfish.extras:glassfish-embedded-all:3.0.1'
providedCompile 'org.glassfish.extras:glassfish-embedded-
all:3.0.1’
}

Java EE 6 security
• Service/Façade
• Declarative (@RolesAllowed)
• Programmatic
• Web Controller
• New annotations for authentication & authorization
• @ServletSecurity @HttpConstraint , @HttpMethodConstraint

• @WebFilter @DeclareRoles @RunAsPresentation
• Transport Layer
• CONFIDENTIAL, INTEGRAL, NONE
• ServletSecurity.TransportGuarantee

@WebServlet(name="UnderwritingServlet", urlPatterns={"/UnderwritingServlet"})
@ServletSecurity(@HttpConstraint(transportGuarantee=ServletSecurity.Transport
Guarantee.CONFIDENTIAL),
))


CDI

• Bean discovery and wiring

public class ItemController {

@Inject
private CatalogService catalogService ;


Bean Validation
public class Address {
@NotNull @Size(max=30,
message="longer than {max} characters")
private String street1;
...
@NotNull @Valid
private Country country;
}

public class Country {
@NotNull @Size(max=30)
private String name;
...
}


Servlet 3.0
• Ease of Development
@WebServlet(urlPatterns=“/foo”,
name=”MyServlet”,
asyncSupported=true)

• @WebFilter("/secured/*")
• Asynchronous Servlet
> Support Comet applications
• Security enhancements


Summary
• REST architecture is gaining popularity
> Simple, scalable and the infrastructure is already in place
• JAX-RS (JSR-311) provides a high level declarative
programming model
> http://jersey.dev.java.net

For More Information
• Reference Implementation
• http://jersey.java.net/

• Java EE 6 tutorial
• http://docs.oracle.com/javaee/6/tutorial/doc/

• Backbone.js JAX-RS example
• http://coenraets.org/blog/2011/12/backbone-js-wine-cellar-tutorial-
part-1-getting-started/
• JAX-RS Comet example
• http://www.oracle.com/technetwork/systems/articles/cometslideshow-
139170.html

For More Information
• RESTful Java with JAX-RS

Rest

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à Rest

Similaire à Rest (20)

Plus de Carol McDonald

Plus de Carol McDonald (20)

Rest