Apache CXF with JAX-RS

JAX-RS is the standard Java API for RESTful services. Resources are ordinary classes annotated with paths and HTTP methods. CXF implements the specification, supplies JSON providers, and can publish REST and SOAP endpoints in the same application.

Core annotations

• @Path - the URL segment for a resource class or method.
• @GET, @POST, @PUT, @DELETE, @PATCH - the HTTP method.
• @Produces - the response media type, such as application/json.
• @Consumes - the request media type.
• @PathParam, @QueryParam, @HeaderParam - parameter binding.
• @Provider - classes that handle JSON, exceptions, or cross-cutting behavior.

package com.example.rest;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.PathParam;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/hello")
public class HelloResource {

    @GET
    @Path("/{name}")
    @Produces(MediaType.TEXT_PLAIN)
    public String greet(@PathParam("name") String name) {
        return "Hello, " + name;
    }
}

JSON support

CXF does not serialize arbitrary objects to JSON by itself. Register a JSON provider, commonly Jackson, and CXF will use it based on the @Produces and @Consumes annotations. Add the provider dependency and register the provider with the server factory.

<dependency>
    <groupId>com.fasterxml.jackson.jaxrs</groupId>
    <artifactId>jackson-jaxrs-json-provider</artifactId>
    <version>2.17.0</version>
</dependency>

JAX-RS versus JAX-WS

• REST models resources and uses HTTP verbs; SOAP models operations and uses a single POST endpoint.
• REST payloads are usually JSON; SOAP payloads are XML envelopes.
• REST relies on HTTP caching and status codes; SOAP defines faults in the envelope.
• JAX-RS contracts can be described with OpenAPI; JAX-WS contracts use WSDL.
• Both can coexist in one CXF application, which is useful during a gradual migration.

Status codes

Return the correct status for the outcome. A created resource should return 201 with a Location header; a missing record should return 404; invalid input should return 400 or 422.

import jakarta.ws.rs.core.Response;

@POST
@Consumes(MediaType.APPLICATION_JSON)
public Response create(Employee employee) {
    Employee saved = repository.save(employee);

    return Response
        .created(URI.create("/employees/" + saved.id()))
        .entity(saved)
        .build();
}

Providers

Exception mappers turn thrown exceptions into consistent JSON errors. Filters can log requests, enforce authentication, or add response headers. Keep these concerns out of resource methods so the resource code stays focused on the endpoint's purpose.

@Provider
public class NotFoundMapper implements ExceptionMapper<EntityNotFoundException> {
    @Override
    public Response toResponse(EntityNotFoundException e) {
        return Response.status(404)
            .entity(Map.of("message", e.getMessage()))
            .type(MediaType.APPLICATION_JSON)
            .build();
    }
}

Design guidance

Use nouns for paths, let HTTP methods express actions, and keep response shapes stable. Version the API when a breaking change is unavoidable. The next chapters publish a resource and then consume it with a JAX-RS client.

Back to course overview · Previous: Create WSDL Client & Test · Next: Create JAX-RS Server