Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
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¶m2=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?
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.
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.
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.
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.
