Sagara  Gunathunga  Architect  -­‐  WSO2  

Deep  dive  into  JAX-­‐RS  

2  

   REST    

REpresentational State Transfer

“An architecture style of networked systems & uses HTTP Protocol for data communication ”

3  

   REST    Fundamentals      

Resources with unique IDs

Standard methods

Multiple representations

Link Resources together

HTTP Content (JSON/POX/TXT)

HTTP URL

Hyperlinks

HTTP Methods

4  

   REST    Fundamentals      

5  

   REST    Fundamentals      •  Client-Server

•  Separation principle •  Components Independent

•  Stateless •  Session state on the client •  Visibility, reliability and scalability •  Trade off (network performance, etc.)

•  Cacheable •  A response can be cacheable •  Efficiency but reduce reliability

•  Layered system •  System scalability

6  

JAX-­‐RS  –  Java  API  for  RESTfull                                                            WebServices    

•  Annotation driven JavaEE API

•  Expose annotated Java bean as HTTP based services •  Implementation may support service descriptions. •  Swagger •  RAML •  WADL

•  Define JAVA ó HTTP mapping •  Number of implementations •  Apache CXF •  Apache Wink •  Jersey

•  Also used by Microservices frameworks to define services •  Dropwizard •  Spring Boot

7  

Richardson  Maturity  Model  

8  

RMM  –  Level  0    

•  HTTP as a transport system for remote interactions.

•  Same as SOAP or XML-RPC it's basically the same mechanism.

•  Most of the cases only one endpoint is exposed for whole service/application.

9  

RMM  –  Level  1    

•  For each web resource there is a unique identifiable Id. •  http://school.com/api/students => All student collection •  Http://scholl.com/api/student/2345 => A unique student

10  

RMM  –  Level  2    

•  Map HTTP Methods to operations (state transition) on resources. •  GET Http://scholl.com/api/student/2345 •  PUT Http://scholl.com/api/student/2345 •  DELETE Http://scholl.com/api/student/2345

•  Do not overload HTTP POST/GET and define WS like operations.

•  Do not use “verbs/actions” as a part of resource URL. •  E.g – createStudent, editStudent

• 

11  

HTTP Method CRUD Desc.

POST CREATE Create -

GET RETRIEVE Retrieve Safe,Idempotent,Cacheable

PUT UPDATE Update Idempotent

DELETE DELETE Delete Idempotent

   REST  HTTP Methods  

12  

RMM  –  Level  3    

•  Use Hyperlinks to relate (link) resources.

•  Also known as HATEOAS (Hypertext As The Engine Of Application State).

13  

JAX-­‐WS  AnnotaGons    •  @Path

•  @GET

•  @PUT

•  @POST

•  @DELETE

•  @Produces

•  @Consumes

•  @PathParam

•  @QueryParam

•  @MatrixParam

•  @HeaderParam

•  @CookieParam

•  @FormParam

•  @DefaultValue

•  @Context

JAX-­‐RS  

JAX-RS Annotated Service

@Path("/hello”)public class HelloWorldService {

@GET @Path("/{user}") public String hello(@PathParam("user") String user) {

} }

JAX-­‐RS  

JAX-RS Annotated Service

@Path("/hello”)public class HelloWorldService {

@GET @Consumes("text/plain") @Produces("text/xml") @Path("/{user}") public String hello(@PathParam("user") String user) {

} }

JAX-­‐RS  parameter  types  •  @PathParam

•  @QueryParam •  @HeaderParam

•  @CookieParam

•  @FormParam

•  @MatrixParam

JAX-­‐RS  Path  parameters   @GET @Path("/hello/{user}") public String hello(@PathParam("user") String user) { return "Hello " + user; }

http://localhost:8080/helloworldapp/hello/sagara

PathParam “user” value

•  URL template style •  Generally used to represent compulsory

user inputs

JAX-­‐RS  OpGonal  Path  parameters   @GET @Path("/hello{user: (/user)?}") public String hello(@PathParam("user") String user) { return "Hello " + user; }

http://localhost:8080/helloworldapp/hello/sagara

PathParam “user” value

•  Important in backward compatible API designs.

•  Generally incorporate with @DefaultValue annotation

http://localhost:8080/helloworldapp/hello/

No PathParam “user” value

http://localhost:8080/helloworldapp/hello

JAX-­‐RS  Query  parameters   @GET @Path("/hello") public String hello(@QueryParam (”name") String user) { return "Hello " + user; }

http://localhost:8080/helloworldapp/hello?name=sagara

PathParam “user” value•  Query string parameter style

•  Generally used to represent optional user inputs or controller operations.

•  Generally incorporate with @DefaultValue annotation

JAX-­‐RS  Header  parameters   @GET @Path("/hello") public String hello(@HeaderParam("Referer") String referer) { return "Hello World ” ; }

GET /helloworldapp/hello http/1.1Host localhost Referer http://facebook/…….. Header value

•  Map HTTP header values to Java method parameters.

•  Can be used to handle resource versioning , pagination, cache etc.

21  

 Error  handling    -­‐  Status  Codes      Do not define your own error codes instead use HTTP status codes as much as possible.

HTTP 200 - OKHTTP 201 - Resource createdHTTP 204 - No content foundHTTP 30 4 - Not modified

HTTP 404 - Resource not found HTTP 410 - Resource goneHTTP 409 - Conflicts HTTP 403 - Forbidden

HTTP 500 - Internal Server Error HTTP 503 - Service Unavailable

22  

 Error  handling    -­‐  Status  Codes      Do not define your own error codes instead use HTTP status codes as much as possible.

public Response findAll() { try { return Response.status(Response.Status.ACCEPTED)

.entity(users.findAll()).build(); } catch (UserDAOException e) { return Response.

status(Response.Status.INTERNAL_SERVER_ERROR).build(); } }

23  

 Error  handling  -­‐  ExcepGonMapper  Instead of scatter error handling code in resource code possible to define .

class UserExceptionMapper implements ExceptionMapper<UserDAOException> {

public Response toResponse(UserDAOException exception) {

if (exception instanceof UserNotFoundException) { return Response.status(Response.Status.NOT_FOUND).build();

} else { return Response .status(Response.Status.INTERNAL_SERVER_ERROR).build(); } }

24  

Resource  Linking  Use hyper links properly to link related resources.

Account can be in many

groups

Link to related group

Links to group members

25  

JAX-­‐RS  PaginaHon  Widely used approaches. •  LimitOffset based pagination

•  Limit – Define the size of the page •  Offset – Define the starting point of each page.

•  Curser based pagination

•  Limit – Define the size of the page •  Before –

Cursor that points to the start of the page of data that has been returned

•  After - cursor that points to the end of the page of data that has been returned

•  Time based pagination •  Limit – Define the size of the page •  Until – points to the end of the range of time-based data •  Since – points to the startof the range of time-based data

26  

JAX-­‐RS  LimitOffset  based  PaginaHon  @GET@Path("/users")@Produces(MediaType.APPLICATION_JSON)public Response findAll(

@QueryParam("offset") @DefaultValue("0") int offset, @QueryParam("limit") @DefaultValue("10") int limit,

@Context UriInfo uriInfo) { }

URI currentLink = UriBuilder.fromUri(uriInfo.getBaseUri()).path("/page/users")

.queryParam("offset", offset) .queryParam("limit", limit) .build();

Creating Links

27  

AuthenHcaHon  and  AuthorizaHon    Widely used approaches. •  HTTP BasicAuth •  OAuth2

28  

References      

•  https://github.com/sagara-gunathunga/jaxrs-java-colombo/

•  http://martinfowler.com/articles/richardsonMaturityModel.html

Contact  us  !