REST API: Request body as JSON or plain POST data?

Question

I'm currently building a REST API. All GET methods currently use JSON as response format. Whats the best practice on POST and PUT operations? Use JSON in the request body or plain POST? I cannot find anything about this matter.

I see Twitter uses POST for instance: https://dev.twitter.com/docs/api/1/post/direct_messages/new

What are the benefits of using a JSON format? The API controller (which is half done) I got from github expects JSON. Really wondering why I would choose using that.

Answer 1

It depends on the data you want to exchange. If it is a complex structure you need to send it in a structured way (e.g. XML or JSON). In java web applications json is more lightweight, so it's preferable over XML.

If you want to send a few fields from a form "application/x-www-urlformencoded" type could be used as well.

Answer 2

POST, PUT, GET are all HTTP verbs and do not, in and of themselves, indicate a format for transferring the data, so there is no POST format. That means that you can encode the data in any way you choose.

Now, what format you decide to go with should really be more a matter of how your API will generally be used. If it will be primarily fielding form submits from a web browser, then using a form fields encoding is likely the most reasonable thing to do since it makes that interaction easier for the client.

On the other hand, if you are primarily going to be receiving JSON data from AJAX calls, then receiving a JSON format may make sense. If you will do both, there isn't any reason you can't accept data in both formats.

The other aspect to consider is the complexity of the data structures you will be passing back and forth. Form encoding (similar to query-string encoding as well) is a key-value structure, while JSON (or XML) allows for a much richer data structure.

In the end, go with whatever is simplest for both you on the server side, as well as you on the client side (since I assume you will also be writing the primary client consumer of the API in question). Simplicity is always preferred over complexity until you can definitively show that more complexity gives you a measurable benefit.

Also, the last thing I will mention is that REST isn't just about clean URLs or using HTTP verbs correctly. Those aspects are really just icing on the cake. The core idea behind a REST architecture is that Hypertext is the engine of application state. By simply following URLs in the server responses, a good client can learn about all of the available actions and doesn't need to know anything more than the base URL. Everything else can be discovered from that. Couple that with well defined content types and you have a world where lots of clients can communicate with lots of servers, all speaking the same "language", and the clients don't need to know anything about the servers (or vice-versa) other than the base URL and the content types. That's what REST is all about.