CODEWITHSUNDEEP
json-api
Jeroen Knoef
Jeroen Knoef

Reputation: 297

How to create compound documents?

I'm thinking of using the JSONAPI standard for the design of our API. One thing this API must be able to do, is accept a compound document (several layers deep) and create it. The root object owns all descendants ('to-many' relationships) which the server knows nothing about at that point, so it's not possible for the client to provide an id.

Is this supported by the specification or does the client have to issue http requests for every object in the document in order?

Upvotes: 20

Views: 1515

Answers (2)

user521990
user521990

Reputation: 829

While this question is old - JSONAPI now has a standard for creating a (POST) complex document called atomic.

https://jsonapi.org/ext/atomic/

Example:

{
  "atomic:operations": [
  {
   "op": "add",
   "data": {
     "type": "authors",
     "id": "acb2ebd6-ed30-4877-80ce-52a14d77d470",
     "attributes": {
       "name": "dgeb"
     }
   }
  }, 
 {
  "op": "add",
  "data": {
     "type": "articles",
     "id": "bb3ad581-806f-4237-b748-f2ea0261845c",
     "attributes": {
       "title": "JSON API paints my bikeshed!"
     },
     "relationships": {
       "author": {
         "data": {
           "type": "authors",
           "id": "acb2ebd6-ed30-4877-80ce-52a14d77d470"
          }
         }
        }
       }
     }
  ]
}

Upvotes: 0

equivalent8
equivalent8

Reputation: 14237

from http://jsonapi.org/format/#document-compound-documents

Compound documents require "full linkage", meaning that every included resource MUST be identified by at least one resource identifier object in the same document. These resource identifier objects could either be primary data or represent resource linkage contained within primary or included resources. The only exception to the full linkage requirement is when relationship fields that would otherwise contain linkage data are excluded via sparse fieldsets.

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON API paints my bikeshed!"
    },
    "links": {
      "self": "http://example.com/articles/1"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "first-name": "Dan",
      "last-name": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}

Upvotes: 5

Related Questions