Rest API Content-Type header question

[nguyen-tri-nhan]

I have an existed POST API, now I want to add a body for it. To be backward compatible, the body is optional.

    @POST
    @Path("/")
    @Blocking
    fun myPostApi(
        @Valid body: MyBody?
    ): RestResponse<Unit> {
        doSth(body)
        return Response.ok()
    }

data class MyBody(
  myField: String?
)

Then when I perform an API call to it without a body, it throw HTTP 415 from both PostMan and frontend.
Can you please explain why? Thank you

[quarkus-bot[bot]]

/cc @geoand (kotlin)

[geoand]

When using the hibernate-orm-quickstart and doing a POST to http://localhost:8080/fruits with an empty body, I don't get HTTP 415, so what you are seeing in not a general handling of empty body

[nguyen-tri-nhan]

I did not add these 2 annotations

@Produces("application/json")
@Consumes("application/json")

That would be a reason, isn't it?

[geoand]

In the case of the quickstart, they aren't actually needed, but in your case, yes, they could be needed

[nguyen-tri-nhan]

Sure, that why I'm trying to explore what happens 😿

[Thamidu-Nadun]

Even though the method accepts a nullable body, the server still expects a Content-Type: application/json and then it tries to deserialize the body.

To solve the issue, I would recommend method overloading.

Handle POST with no body

@POST
@Path("/")
@Blocking
fun myPostApiNoBody(): RestResponse<Unit>

Handles POST with application/json body

@POST
@Path("/")
@Consumes(MediaType.APPLICATION_JSON)
@Blocking
fun myPostApiWithBody(@Valid body: MyBody?): RestResponse<Unit>

[nguyen-tri-nhan]

I have tried with

@POST
@Path("/")
@Consumes(MediaType.APPLICATION_JSON)
@Blocking
fun myPostApiWithBody(@Valid body: MyBody?): RestResponse<Unit>

And it works for both cases, so I think the key answer here is using @Consumes(MediaType.APPLICATION_JSON), but I'm struggling to explore how it works.

[Thamidu-Nadun]

If the client/API testing tool sees an HTTP body has content, then the tool adds Content-Type to the HTTP header.

POST /save HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id": 123,
    "firstName": "Paul",
    "lastName": "Klee",
    "email": "p.klee@example.com"
}

If there is no content in the body and Content-Type is set to some value, that may result in a 415 (Unsupported Media Type ) error.

POST /save HTTP/1.1
Host: example.com
Content-Type: application/json

Since the Content-Type header is set server tries to parse it. Since an empty body is not a valid JSON server, return a 415 error.

If there is no body and no Content-Type header server treats it as no content.

POST /save HTTP/1.1
Host: example.com

Tip

If you want to accept any type use kotlin @Consumes(MediaType.WILDCARD)

Warning

Use it carefully

Note

Here are the few Content-Type headers that may be helpful.

1. application/x-www-form-urlencoded
2. multipart/form-data;boundary="delimiter12345"
3. text/css
4. text/javascript

Note

You can find more about Content-Type in this MDN docs
and POST Request