JSON vs Form POST

Question

We\'re having a bit of a discussion on the subject of posting data to a REST endpoint. Since the objects are quite complex, the easiest solution is to simply serialize them

Answer 1

You can use JSON as part of the request data as the OP had stated all three options work.

The OP needs to support JSON input as it had to support contain complex structural content. However, think of it this way... are you making a request to do something or are you just sending what is basically document data and you just happen to use the POST operation as the equivalent of create new entry.

That being the case, what you have is basically a resource endpoint with CRUDL semantics. Following up on that you're actually not limited to application/json but any type that the resource endpoint is supposed to handle.

For non-resource endpoints

I find that (specifically for JAX-RS) the application/x-www-urlencoded one is better.

1. Consistency with OAuth 2.0 and OpenID Connect, they use application/x-www-urlencoded.
2. Easier to annotate the individual fields using Swagger Annotations
3. Swagger provides more defaults.
4. Postman generates a nice form for you to fill out and makes things easier to test.

Examples of non-resource endpoints:

• Authentication
• Authorization
• Simple Search (though I would use GET on this one)
• Non-simple search where there are many criteria
• Sending a message/document (though I would also consider multipart/form-data so I can pass meta data along with the content, but JAX-RS does not have a standard for this one Jersey and RestEasy have their own implementations)