POSTing multiple documents

[GavinJoyce]

It seems that the spec is setup to support POSTing multiple documents in one request : https://github.com/json-api/json-api/pull/66.

POST /photos
Content-Type: application/json
Accept: application/json

{
  "photos": [{
    "title": "Ember Hamster",
    "src": "http://example.com/images/productivity.png"
  }, {
    "title": "RestPack Armadillo",
    "src": "http://example.com/images/super-productivity.png"
  }]
}

I'd like to document these rules in the Creating a Document section.

Is it a MUST or a MAY that the server support creating multiple documents in this way? A MUST seems to make most sense. I'll submit a PR once this is clear.

[gr0uch]

I think this is correct, or at least it's how I implemented it in my json-api project. +1 to making it a MUST.

[zikes]

Since the server MUST return a Location header for the newly created document, how should that be formatted in the case of multiple new documents? If it is a multi-document Location, how do you resolve that with an individually identifying href for each document in the response, since they MUST match?

[GavinJoyce]

How about this: The server MUST return a Location header which represents the location of the newly created resource(s)?

For a single document:

HTTP/1.1 201 Created
Location: http://example.com/photos/12
Content-Type: application/json

{
  "photos": [{
    "id": "12",
    "href": "http://example.com/photos/12",
    "title": "Ember Hamster",
    "src": "http://example.com/images/productivity.png"
  }]
}

For multiple:

HTTP/1.1 201 Created
Location: http://example.com/photos?ids=12,13
Content-Type: application/json

{
  "photos": [{
    "id": "12",
    "href": "http://example.com/photos/12",
    "title": "Ember Hamster",
    "src": "http://example.com/images/productivity.png"
  }, {
    "id": "13",
    "href": "http://example.com/photos/13",
    "title": "RestPack Armadillo",
    "src": "http://example.com/images/super-productivity.png"
 }]
}

[steveklabnik]

202 is a superset of this.