7

I am building my first serious API. I am trying to decide how users should POST data.

I could allow them to POST variables, which is what HTML forms do.

param1=foo&param2=bar

Or I can let them POST JSON, which also makes sense because I will be returning a JSON response to the user.

{"param1":"&","param2":"bar"}

Is there a formal standard to which of these should be used? Are there strong arguments towards or against either of these approaches?

  • 2
    Also consider that the with JSON is easy to build complicated (nested) data structures, while with the form method is probably way too complicated. So you could use both methods, but sometimes JSON might be the mandatory choice. – Adrian Iftode Jun 1 '17 at 22:24
  • The question is really about how the client should encode the data in their request bodies - either as x-www-form-urlencoded like a browser would do, or as json. – bdsl Jun 5 '17 at 21:26
14

JSON is (by far) the most flexible and modern option of the two, so I would go for that. Especially if you have already decided to return a response in JSON.

That said, there's no reason you can't support both, if this is beneficial for the consumers of your API. HTML forms submit their content with an HTTP request where the Content-Type HTTP header will be set to application/x-www-form-urlencoded, while the correct content type for JSON is application/json.

Some frameworks, e.g. ASP.NET Web API offer some automatic serialization of the incoming request (whether it is XML or JSON, I'm not sure if this framework supports form encoding), lifting the burden of this task from you.

If you're creating REST APIs, you can use the Swagger specification; it's a definition format (YAML) to describe RESTful APIs creating an interface for easily developing and consuming an API by mapping the resources and operations associated with it. It's language agnostic so you can generate services for many Server/Client-side languages, it's readable, and above all generates a nice API specification documentation.

|improve this answer|||||
  • 1
    One thing that might have to be taken into account is the size of the POST data when using query parameters. Some clients may impose a limit on how much they handle. See stackoverflow.com/a/812962/146205 for a more detailed write-up. – Jensen Jun 4 '17 at 7:03
  • @Jensen I don't think the question is about sending POST data as query parameters, it's about sending POST data as a form-encoded body message. – Jack Jun 5 '17 at 21:25
6

Having them post json let's you be more versatile and precise in the data structures you receive; however, POST variables let your API be easily used by web browsers.

If you know the requests will always be server to server, or you have very complex inputs, I would go with json. If your inputs are very simple, it will make your API more easily used if you use POST vars.

|improve this answer|||||
1

Or I can let them POST JSON, which also makes sense because I will be returning a JSON response to the user.

Well, the response format should not constrain or condition the request format.

It might interest you the postel's law, also known as Robustness principle.

It is good to support different representantion formats for both request and response. The key of the robustness lays on the strict representantation of the resource (model or data structure), not its format (json, xml, csv).

So, regarding to the question. A good practice could be supporting both (quey strings and request body).

Just a little consideration related to the API security. For endpoints meant to comunicate sensitive data (passwords, tokens, personal data) it's recommended to don't post the data via query strings. Instead use the JSON approach or http headers.

|improve this answer|||||
  • Your link is broken. – Goose Jun 4 '17 at 1:58
  • @Goose, srry. Fixed! – Laiv Jun 4 '17 at 5:55
0

Posting the json object allows for more flexibility, especially if you want to use DateTime as one of your parameters. The query string is also length limited if the parameters are heavy at all.

However, for simple Post requests you can supply both options, it's an extra method in Asp.Net.

|improve this answer|||||

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.