Java colombo-deep-dive-into-jax-rs

1. Sagara
Gunathunga
Architect
-­‐
WSO2
Deep
dive
into
JAX-­‐RS

2. 2
REST
REpresentational State Transfer
“An architecture style of networked systems & uses
HTTP Protocol for data communication ”

3. 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. 4
REST
Fundamentals

5. 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. 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. 7
Richardson
Maturity
Model

8. 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. 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. 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. 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. 12
RMM
–
Level
3
• Use Hyperlinks to relate (link) resources.
• Also known as HATEOAS (Hypertext As The Engine Of Application
State).

13. 13
JAX-­‐WS
AnnotaGons
• @Path
• @GET
• @PUT
• @POST
• @DELETE
• @Produces
• @Consumes
• @PathParam
• @QueryParam
• @MatrixParam
• @HeaderParam
• @CookieParam
• @FormParam
• @DefaultValue
• @Context

14. JAX-­‐RS
JAX-RS Annotated Service
@Path("/hello”)
public class HelloWorldService {
@GET
@Path("/{user}")
public String hello(@PathParam("user") String user) {
}
}

15. 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) {
}
}

16. JAX-­‐RS
parameter
types
• @PathParam
• @QueryParam
• @HeaderParam
• @CookieParam
• @FormParam
• @MatrixParam

17. 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

18. 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

19. 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

20. JAX-­‐RS
Header
parameters
@GET
@Path("/hello")
public String hello(@HeaderParam("Referer") String referer) {
return "Hello World ” ;
}
GET /helloworldapp/hello http/1.1
Host 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. 21
Error
handling
-­‐
Status
Codes
Do not define your own error codes instead use HTTP status codes
as much as possible.
HTTP 200 - OK
HTTP 201 - Resource created
HTTP 204 - No content found
HTTP 30 4 - Not modified
HTTP 404 - Resource not found
HTTP 410 - Resource gone
HTTP 409 - Conflicts
HTTP 403 - Forbidden
HTTP 500 - Internal Server Error
HTTP 503 - Service Unavailable

22. 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. 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. 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. 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. 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. 27
AuthenHcaHon
and
AuthorizaHon
Widely used approaches.
• HTTP BasicAuth
• OAuth2

28. 28
References
• https://github.com/sagara-gunathunga/jaxrs-java-colombo/
• http://martinfowler.com/articles/richardsonMaturityModel.html

29. Contact
us
!