Unravel › Java concepts › APIs and web

Learn these first

At a glance

1. 1@Path("/orders") on a class sets the base route; @GET, @POST on methods choose the HTTP verb; @Path("{id}") adds a sub-path and @PathParam("id") reads it@QueryParam reads a query parameter.
2. 2@Consumes(MediaType.APPLICATION_JSON) and @Produces(...) select the content types; a message body writer (JSON-B or Jackson) converts objects to and from the body
3. 3Return a POJO for 200, or a Response (Response.created(uri).entity(x).build()) to control the status and headers
4. 4Errors: throw WebApplicationException subclasses (NotFoundException) or register an ExceptionMapper<T> to convert exceptions into responses in one place

• Filters and interceptors (ContainerRequestFilter, ContainerResponseFilter) are the JAX-RS counterpart of servlet filters, used for authentication, CORS and logging
• Resource classes are request-scoped by default in most implementations (a new instance per request), unlike Spring singletons, so fields are not shared state unless you mark the class @Singleton
• At deployment the runtime (Jersey, RESTEasy, CXF) scans for @Path classes and builds a routing tree from the path templates

@Path("/orders")@Produces(MediaType.APPLICATION_JSON)public class OrderResource {    @Inject    OrderService service;    @GET    @Path("{id}")    public Order get(@PathParam("id") long id) {        return service.find(id).orElseThrow(NotFoundException::new);    }    @POST    @Consumes(MediaType.APPLICATION_JSON)    public Response create(OrderRequest request, @Context UriInfo uri) {        Order created = service.create(request);        return Response.created(uri.getAbsolutePathBuilder().path("" + created.id()).build()).entity(created).build();    }}

1. line 1 uses Path, the core of JAX-RS (Jakarta REST) resources
2. line 2 uses Produces, the core of JAX-RS (Jakarta REST) resources
3. line 7 uses GET, the core of JAX-RS (Jakarta REST) resources
4. line 8 uses Path, the core of JAX-RS (Jakarta REST) resources
5. line 9 uses Path, the core of JAX-RS (Jakarta REST) resources
6. line 13 uses POST, the core of JAX-RS (Jakarta REST) resources

How Unravel recognises it

When you paste code, Unravel looks for these signs of jax-rs (jakarta rest) resources. Spotting them yourself is a good habit when you read unfamiliar code:

• Annotations: @Path @GET @POST @PUT @DELETE @PATCH @Produces @Consumes @PathParam @QueryParam @HeaderParam @FormParam @Context @Provider and 1 more
• Types: WebApplicationException ExceptionMapper ContainerRequestFilter ContainerResponseFilter UriInfo ClientBuilder WebTarget ResteasyClient

Part of a learning path

• Jakarta EE and other frameworks · previous: EJB session beans and container services · next: Quarkus applications

Related concepts