How to POST a JSON Object to a JAX-RS Service: Resolving 415 Unsupported Media Type Error

Problem Background and Error Analysis

When using the Jersey framework to implement JAX-RS services, developers often encounter a 415 Unsupported Media Type error when POSTing JSON objects to resource endpoints. This error indicates that the server cannot process the media type provided in the request. From the provided code example, the resource class is annotated with @Consumes(MediaType.APPLICATION_JSON) to declare it accepts JSON input, yet client requests still fail.

Core Issue: Missing Content-Type Header

The root cause is the absence of a Content-Type header in the HTTP request. Although the resource class specifies acceptable media types via the @Consumes annotation, JAX-RS implementations like Jersey rely on the request's Content-Type header to determine how to parse the request body. Without this header, the server cannot identify the format of the request body, leading to a 415 error.

Solution: Add the Correct Content-Type Header

To resolve this, include Content-Type: application/json in the POST request. Here is a corrected HTTP request example:

POST http://localhost:8080/jaxrs-oms/rest/orders HTTP/1.1
Content-Type: application/json

{
    "id": 123,
    "symbol": "AAPL",
    "side": "Buy",
    "quantity": 1000
}

Note: Numeric fields in the JSON object (e.g., id and quantity) should use number types rather than strings, unless the corresponding fields in the Order class are defined as strings. This ensures consistency in serialization and deserialization.

Code Implementation Details

The resource class design must ensure proper mapping from JSON to Java objects. Below is an enhanced OrderResource class with error handling and validation:

@Path("/orders")
@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class OrderResource {
    private static Map<Integer, Order> orders = new HashMap<>();

    @POST
    public Response createOrder(Order order) {
        if (order == null || order.id <= 0) {
            return Response.status(Response.Status.BAD_REQUEST)
                           .entity("Invalid order data")
                           .build();
        }
        orders.put(order.id, order);
        return Response.status(Response.Status.CREATED)
                       .entity(order)
                       .build();
    }

    @GET
    @Path("/{id}")
    public Order getOrder(@PathParam("id") int id) {
        return orders.getOrDefault(id, new Order(0, "Buy", "Unknown", 0));
    }
}

The Order class should provide a no-argument constructor and appropriate getter/setter methods for compatibility with JAX-RS JSON binding:

public class Order {
    private int id;
    private String side;
    private String symbol;
    private int quantity;

    public Order() {}

    public Order(int id, String side, String symbol, int quantity) {
        this.id = id;
        this.side = side;
        this.symbol = symbol;
        this.quantity = quantity;
    }

    // Getter and setter methods
    public int getId() { return id; }
    public void setId(int id) { this.id = id; }
    // ... other getters and setters
}

Understanding Media Type Negotiation

JAX-RS uses @Consumes and @Produces annotations for media type negotiation. When a client sends a request, Jersey checks if the request's Content-Type header matches the media types declared by the resource method. If matched, it uses the appropriate message body reader (e.g., JacksonJsonProvider) to deserialize JSON into a Java object. Otherwise, it returns a 415 error. Similarly, @Produces annotations and the Accept header control response formats.

Common Pitfalls and Best Practices

Beyond missing Content-Type headers, other common issues include mismatched JSON field names and Java property names, lack of no-argument constructors, or unconfigured JSON processing libraries. It is recommended to add JSON support via Jersey's dependency injection, such as by including the jersey-media-json-jackson module via Maven. Additionally, always validate input data and return appropriate HTTP status codes, such as 201 Created for successful resource creation.

Conclusion

By ensuring POST requests include the correct Content-Type: application/json header and optimizing resource and POJO design, the 415 Unsupported Media Type error can be effectively resolved. Understanding JAX-RS's media type negotiation mechanism is key to building robust RESTful services. The code examples and explanations provided in this article aim to help developers deeply grasp these concepts, enhancing API reliability and interoperability.