2. Agenda
• REST Primer
• RESTful Design and API Elements
• Building a Simple Service
• Security
• Q&A
3. 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
4. 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
5. 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
6. Rest Uniform Interface:
Every thing is a Resource
Every resource has an id, URI is the id
http://company.com/customers/123456
7. 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
9. 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
10. 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
12. 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
15. 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
17. 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
18. 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
19. 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
20. 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
21. Agenda
• REST Primer
• RESTful Design and API Elements with JAX-RS
• Building a Simple Service
• Status
• Q&A
22. 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
23. 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(...) {...}
}
24. 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) {
...
}
}
29. 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();
}
}
31. 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);
32. Agenda
• REST Primer
• RESTful Design and API Elements
• Building a Simple Service
• Deployment Options
• Status
34. 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
35. 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
36. RESTful Catalog
Javascript client, JAX-RS, JSON, JPA
Registration Application
JAX-RS class Entity Class
JSON class
Item DB
ItemsResource
javascript client
38. 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>
39. 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"
}
40. 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
41. 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
42. 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>');
});
}
50. Authentication: Configure web.xml
<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
51. Authentication: Configure web.xml
<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
52. Authentication: Configure web.xml
<security-constraint>
...
<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
53. Encryption: Configure web.xml
<security-constraint>
...
<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
54. Authentication: Configure web.xml
<security-role>
<role-name>admin</role-name>
</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
55. Authentication: map roles to realm
<sun-web-app>
<security-role-mapping>
<role-name>admin</role-name>
<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
57. 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() {}
}
58. 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();
}
59. 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
60. 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’
}
65. 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
66. 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