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.
- Consistency with OAuth 2.0 and OpenID Connect, they use
application/x-www-urlencoded
.
- Easier to annotate the individual fields using Swagger Annotations
- Swagger provides more defaults.
- 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)