Create¶

Prerequisite to test following examples is to have an API key with permissions:

Path	Methods	ACL
/resources/news\.article	POST	off
/resources/writer	POST	off

A document can be blank meaning it only has fields type and id. Additionally, it can have attributes and/or relationships.

Blank document¶

Following API request creates a blank document:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "news.article"
  }
}' \
-X POST https://api.jazer.io/resources/news.article

Only member type is required. The response will contain a created document with its unique identifier and link to a document API endpoint:

{
  "data": {
    "type": "news.article",
    "id": "59d40037ac610533b46bbc31",
    "links": {
      "self": "https://api.jazer.io/resources/news.article/59d40037ac610533b46bbc31"
    }
  }
}

Document with attributes¶

Document member attributes can contain arbitrary fields. Example news.article document has following fields:

title - string
rank - number (integer)
published - date

Fields title and rank can be put inside attributes object in the request using plain JSON. Field published needs a special notation to instruct the system to interpret given value as a date. Complete API request:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "news.article",
    "attributes": {
      "title": "Hello World",
      "rank": 5,
      "published": { "$date": "2017-10-03T08:24:50Z" }
    }
  }
}' \
-X POST https://api.jazer.io/resources/news.article

Created document will get a unique identifier. Field published will be parsed as a date and returned in ISO 8601 representation. The response contains a created document:

{
  "data": {
    "type": "news.article",
    "id": "59d403faac610533b46bbc33",
    "attributes": {
      "title": "Kids are smarter than adults",
      "rank": 5,
      "published": "2017-10-03T08:24:50.000Z"
    },
    "links": {
      "self": "https://api.jazer.io/resources/news.article/59d403faac610533b46bbc33"
    }
  }
}

Field published could have been stored as a string. This would not make much difference in this example. However, requests which compare and/or sort documents by published field would return incorrect results since field would be compared as a string and not as a date.

Document with relationships¶

Relationships are structured links to other documents. A link consists of type and id. A relationship can be:

to-one - contains only one link
to-many - contains an array of links

The example news article document has following relationship fields:

author - link to a writer document
associated - links to news.article documents

Before inserting resource news.article with a link to an author, writer document must be created. To keep it simple writer document will have only one attribute field - name. Request creating writer document:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "writer",
    "attributes": {
      "name": "John Smith"
    }
  }
}' \
-X POST https://api.jazer.io/resources/writer

The response contains created writer document:

{
  "data": {
    "type": "writer",
    "id": "59d554c9ac610533b46bbc3e",
    "attributes": {
      "name": "John Smith"
    },
    "links": {
      "self": "https://api.jazer.io/resources/writer/59d554c9ac610533b46bbc3e"
    }
  }
}

Relationship links are validated during document creation. The linked document must exist. Invalid links will return an error. Use created writer ID and previously created news.article IDs to replace parameters in the following API request:

curl -H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H 'api-key: <YOUR_API_KEY_SECURE_ID>' \
-H 'application-id: <YOUR_APPLICATION_ID>' \
-d '
{
  "data": {
    "type": "news.article",
    "relationships": {
      "author": {
        "data": {
          "type": "writer",
          "id": "<WRITER_ID>"
        }
      },
      "associated": {
        "data": [
          {
            "type": "news.article",
            "id": "<NEWS_ARTICLE_1_ID>"
          },
          {
            "type": "news.article",
            "id": "<NEWS_ARTICLE_2_ID>"
          }
        ]
      }
    }
  }
}' \
-X POST https://api.jazer.io/resources/news.article

The response with created news.article document containing relationships:

{
  "data": {
    "type": "news.article",
    "id": "59d55629ac610533b46bbc40",
    "relationships": {
      "author": {
        "links": {
          "self": "https://api.jazer.io/resources/news.article/59d55629ac610533b46bbc40/relationships/author",
          "related": "https://api.jazer.io/resources/news.article/59d55629ac610533b46bbc40/author"
        },
        "data": {
          "type": "writer",
          "id": "59d554c9ac610533b46bbc3e"
        }
      },
      "associated": {
        "links": {
          "self": "https://api.jazer.io/resources/news.article/59d55629ac610533b46bbc40/relationships/associated",
          "related": "https://api.jazer.io/resources/news.article/59d55629ac610533b46bbc40/associated"
        },
        "data": [
          {
            "type": "news.article",
            "id": "59d55367ac610533b46bbc3a"
          },
          {
            "type": "news.article",
            "id": "59d5538eac610533b46bbc3c"
          }
        ]
      }
    },
    "links": {
      "self": "https://api.jazer.io/resources/news.article/59d55629ac610533b46bbc40"
    }
  }
}

Each relationship field has unique API endpoint. Relationships can be therefore directly accessed and modified. Probably the biggest benefit of having relationships is an inclusion of related documents. With one API request document and all requested relationship documents can be fetched.