Java colombo-deep-dive-into-jax-rs
4 likes696 views
This document provides an overview of REST and JAX-RS. It defines REST as an architectural style using HTTP for data communication. Key REST fundamentals are discussed such as resources with unique IDs, standard HTTP methods, and hyperlinks to relate resources. The Richardson Maturity Model for REST APIs is introduced with levels ranging from using HTTP as a simple transport to fully leveraging hypermedia. JAX-RS is defined as a Java annotation-based framework for developing RESTful web services, with annotations explained for defining resources, request parameters, responses, and error handling. The document also covers REST concepts like pagination, authentication, and linking resources.
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 !