POST list of elements using REST

Question

I am looking for an agreement on how to serialize my data when I have a (long) list of elements that I want to send POST to the server.

For example, if I have a /users resource, and I would like to add POST to it, I would http-encode the fields for the new user and put it in the request body as follows: name=foo&age=20

But if I have a list of users like this [{ name: 'foo', age: 20 }, { name: 'bar', age: 10 }] , is there a regular way to POSTing?

I think name[0]=foo&age[0]=20&name[1]=bar&age[1]=10 , but I can't find anything to support it. What do web servers typically accept / expect?

Answer 1

A quick question that can change my answer: are you using POST directly from an HTML form or expect something more complex (like a javascript process or even a web client)

If you have a fairly complex client, you can simply build a JSON and POST string with the content type application/json . Then any resource processes POST, it can use any number of json libraries to read the published string and process as is.

Further Rambling:

What structure / languages ​​do you use to create a REST service? Do they have built-in functionality / conventions that will help you?

For example, if you use JAX-RS to create your service, there is a built-in @FormParam annotation that can be used to process published forms. for example: if you posted the following with the content type application/x-www-form-urlencoded : name=foo&age=20&name=bar&age=10

You can get parallel lists from the service side through:

 @POST @Consumes("application/x-www-form-urlencoded") public void createUsers(@FormParam("name") List<String> name, @FormParam("age") List<String> age) { // Store your users } 

But then you have to deal with the question, what if one list is shorter / longer than the other, how do you solve this? What happens if a new field is required or it is not necessary to create a list of users? (But, as I mentioned earlier, the JSON array of JSON objects solves this problem ... there are many libraries that support automatic JSON deserialization in JAX-RS or there is the option to create your own MessageBodyReader .

(The disclaimer is in the next section: I do not know the rails, my experience is more in the world of Java services ... I base this on this guide ). It looks like Rails has a convention name[]=foo&name[]=bar for automatically processing hosted data in arrays and a similar convention for populating a structure like user[name]=foo&user[age]=20 ... Perhaps if you are on rails Is there a way to use / abuse both of these functions to get the desired result?

Other frameworks and REST languages ​​may have their own conventions and functionality :)

Answer 2

Rails serializes forms in a format that is not similar to what you offer. If you have a nested model, it encodes it like this:

 name=theo&company[name]=acme 

(the equivalent JSON would be {"name": "theo", "company": {"name": "acme"}} )

I cannot say that I saw a Rails application sending arrays, but there is no reason why this would not work (in the worst case, you will get a hash with string keys).

PHP has a different convention if you want to send the array you make

 names[]=alice&names[]=bob&names[]=steve 

But I do not know how you make nested objects this way.

The HTTP specification, or if it is a URI specification, not sure which atm actually indicates that if you pass the same argument multiple times, you will get an array of values ​​(instead of the behavior of most third-party applications). This can be seen in the Jetty API docs, for example: http://api.dpml.net/org/mortbay/jetty/6.1.5/org/mortbay/jetty/Request.html#getParameterValues(java.lang.String )

However, most of them relate to GET requests, not necessarily POST (but perhaps application/x-url-encoded should adhere to the same standards as GET ).

In short, I don’t think there is a standard for this, POST bodies are a little wild western territory. I think, however, that either you should go with JSON because it was done to describe the structures, but application/x-url-encoded not, or you should try to better represent the structure of your data, for example:

 users[0][name]=foo&users[0][age]=20&users[1][name]=bar&users[1][age]=10 

This has some chance of actually being interpreted using the Rails application out of the box, for example.