Skip to content

Storage API ​

The Storage API reads and writes a flat namespace of atoms: objects (structured content) and folders, addressed by path-like keys such as posts/hello-world. Every operation is available two ways: as a method on a StorageRepository in your Node.js code, or over HTTP, once you mount the repository with buildJsonApi from contentia/storage/api. Like every Contentia API server, it requires an access policy.

The Node.js examples call a storage repository; these use the filesystem one. The cURL examples send requests to the mounted API.

ts
import { jsonSerializer } from 'contentia/serializers/json';
import { FileSystemStorageRepository } from 'contentia/storage/fs';

export const storage = new FileSystemStorageRepository('./content', { json: jsonSerializer }, 'json');
sh
export CONTENTIA_URL=https://cms.example.com/storage
export CONTENTIA_TOKEN=your-api-token

Keys in URLs. The key is the one path segment after the resource, so a slash in a key must be percent-encoded: posts/hello-world is /objects/posts%2Fhello-world. A URL with more segments after the key, such as /objects/posts/hello-world, is rejected with 400 invalid_data. A trailing slash is ignored: GET /atoms/ is GET /atoms.

Content. An object's content is a JSON object, and text goes in its body field: a raw string is sent as { "body": "…" }, markdown with frontmatter as { ...frontmatter, "body": "…" }. A repository that stores raw files (rawSerializer) keeps only body and rejects any other field at write time; use jsonSerializer for multi-field content. Every built-in backend sets createdAt and updatedAt, though the schema marks them optional.

Pagination. A listing without page[*] parameters returns the first page of 100. The built-in storage backends page by offset or page number only: they report pagination.styles.cursor: false, so page[after] and page[before] return 400. Conventions covers the parameters.

Capabilities​

Backend capability introspection


Underlying storage repository capabilities​

GET/capabilities

Resolved from the repository on every request, so a swapped-out backend is reflected immediately.

Responses​

The storage-capabilities resource.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "storage-capabilities",
  
  
"id": "self",
  
  
"attributes": {
  
  
  
"compatibilityDate": "2024-01-01",
  
  
  
"changes": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
},
  
  
  
"fileExtensions": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
},
  
  
  
"pagination": {
  
  
  
  
"supported": false,
  
  
  
  
"description": "string"
  
  
  
}
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}
ts
await storage.getCapabilities();
sh
curl "$CONTENTIA_URL/capabilities" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json"

Atoms​

Folder listings over objects and folders (atoms)


List atoms in the root folder​

GET/atoms

Parameters​

Query Parameters

page[number]

Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.

Type
integer
Minimum
1
page[size]

Items per page. Combines with page[number], page[after] or page[before]; on its own it asks for the first page of that many items. With no page[*] parameter at all a page holds 100 items; when page[number], page[after] or page[before] comes without page[size], the backend picks the page size. Values outside 1 to 100 are clamped into that range rather than rejected.

Type
integer
Minimum
1
page[offset]

Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.

Type
integer
Minimum
0
page[limit]

Maximum number of items to return. Read only together with page[offset]; on its own it is ignored and the request gets page 1 of 10 items. Values outside 1 to 100 are clamped into that range.

Type
integer
Minimum
1
page[after]

Forward cursor. Pass an empty value to start a cursor iteration from the beginning, then follow links.next. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string
page[before]

Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string
filter[depth]

Recursion depth for the folder walk. Values that are not integers >= 1 fall back to 1.

Type
integer
Minimum
1
Default
1

Responses​

Atoms in the folder, with pagination links and optional meta.page.total / meta.warnings.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "object",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"content": {
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
},
  
  
  
  
"createdAt": "string",
  
  
  
  
"updatedAt": "string"
  
  
  
},
  
  
  
"meta": {
  
  
  
  
"extension": "string",
  
  
  
  
"revisionId": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"links": {
  
  
  
  
"self": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"links": {
  
  
"self": "string",
  
  
"first": "string",
  
  
"prev": "string",
  
  
"next": "string"
  
},
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.listAtoms('', {
  depth: 1,
  pagination: { perPage: 100 },
}).collect();
sh
curl "$CONTENTIA_URL/atoms" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json"

List atoms in a folder​

GET/atoms/{key}

Parameters​

Query Parameters

page[number]

Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.

Type
integer
Minimum
1
page[size]

Items per page. Combines with page[number], page[after] or page[before]; on its own it asks for the first page of that many items. With no page[*] parameter at all a page holds 100 items; when page[number], page[after] or page[before] comes without page[size], the backend picks the page size. Values outside 1 to 100 are clamped into that range rather than rejected.

Type
integer
Minimum
1
page[offset]

Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.

Type
integer
Minimum
0
page[limit]

Maximum number of items to return. Read only together with page[offset]; on its own it is ignored and the request gets page 1 of 10 items. Values outside 1 to 100 are clamped into that range.

Type
integer
Minimum
1
page[after]

Forward cursor. Pass an empty value to start a cursor iteration from the beginning, then follow links.next. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string
page[before]

Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string
filter[depth]

Recursion depth for the folder walk. Values that are not integers >= 1 fall back to 1.

Type
integer
Minimum
1
Default
1

Responses​

Atoms in the folder, with pagination links and optional meta.page.total / meta.warnings.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "object",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"content": {
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
},
  
  
  
  
"createdAt": "string",
  
  
  
  
"updatedAt": "string"
  
  
  
},
  
  
  
"meta": {
  
  
  
  
"extension": "string",
  
  
  
  
"revisionId": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"links": {
  
  
  
  
"self": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"links": {
  
  
"self": "string",
  
  
"first": "string",
  
  
"prev": "string",
  
  
"next": "string"
  
},
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.listAtoms('posts', {
  depth: 2,
  pagination: { perPage: 100 },
}).collect();
sh
curl -G "$CONTENTIA_URL/atoms/posts" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  --data-urlencode "filter[depth]=2"

Read an atom (object or folder)​

GET/atom/{key}

Responses​

The object or folder at the key, possibly with meta.warnings.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "object",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
},
  
  
"meta": {
  
  
  
"extension": "string",
  
  
  
"revisionId": "string",
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.getAtom('posts/hello-world');
sh
curl "$CONTENTIA_URL/atom/posts%2Fhello-world" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json"

List atom summaries (lightweight listing) in the root folder​

GET/atom-summaries

Parameters​

Query Parameters

page[number]

Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.

Type
integer
Minimum
1
page[size]

Items per page. Combines with page[number], page[after] or page[before]; on its own it asks for the first page of that many items. With no page[*] parameter at all a page holds 100 items; when page[number], page[after] or page[before] comes without page[size], the backend picks the page size. Values outside 1 to 100 are clamped into that range rather than rejected.

Type
integer
Minimum
1
page[offset]

Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.

Type
integer
Minimum
0
page[limit]

Maximum number of items to return. Read only together with page[offset]; on its own it is ignored and the request gets page 1 of 10 items. Values outside 1 to 100 are clamped into that range.

Type
integer
Minimum
1
page[after]

Forward cursor. Pass an empty value to start a cursor iteration from the beginning, then follow links.next. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string
page[before]

Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string
filter[depth]

Recursion depth for the folder walk. Values that are not integers >= 1 fall back to 1.

Type
integer
Minimum
1
Default
1

Responses​

Atom summaries in the folder, with pagination links and optional meta.page.total / meta.warnings.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "object-summary",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"createdAt": "string",
  
  
  
  
"updatedAt": "string"
  
  
  
},
  
  
  
"links": {
  
  
  
  
"self": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"links": {
  
  
"self": "string",
  
  
"first": "string",
  
  
"prev": "string",
  
  
"next": "string"
  
},
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.listAtomSummaries('', {
  depth: 1,
  pagination: { perPage: 100 },
}).collect();
sh
curl "$CONTENTIA_URL/atom-summaries" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json"

List atom summaries (lightweight listing) in a folder​

GET/atom-summaries/{key}

Parameters​

Query Parameters

page[number]

Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.

Type
integer
Minimum
1
page[size]

Items per page. Combines with page[number], page[after] or page[before]; on its own it asks for the first page of that many items. With no page[*] parameter at all a page holds 100 items; when page[number], page[after] or page[before] comes without page[size], the backend picks the page size. Values outside 1 to 100 are clamped into that range rather than rejected.

Type
integer
Minimum
1
page[offset]

Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.

Type
integer
Minimum
0
page[limit]

Maximum number of items to return. Read only together with page[offset]; on its own it is ignored and the request gets page 1 of 10 items. Values outside 1 to 100 are clamped into that range.

Type
integer
Minimum
1
page[after]

Forward cursor. Pass an empty value to start a cursor iteration from the beginning, then follow links.next. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string
page[before]

Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).

Type
string
filter[depth]

Recursion depth for the folder walk. Values that are not integers >= 1 fall back to 1.

Type
integer
Minimum
1
Default
1

Responses​

Atom summaries in the folder, with pagination links and optional meta.page.total / meta.warnings.

application/vnd.api+json
JSON
{
  
"data": [
  
  
{
  
  
  
"type": "object-summary",
  
  
  
"id": "string",
  
  
  
"attributes": {
  
  
  
  
"createdAt": "string",
  
  
  
  
"updatedAt": "string"
  
  
  
},
  
  
  
"links": {
  
  
  
  
"self": "string",
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"links": {
  
  
"self": "string",
  
  
"first": "string",
  
  
"prev": "string",
  
  
"next": "string"
  
},
  
"meta": {
  
  
"page": {
  
  
  
"total": 0
  
  
},
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.listAtomSummaries('posts', {
  depth: 2,
  pagination: { perPage: 100 },
}).collect();
sh
curl -G "$CONTENTIA_URL/atom-summaries/posts" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  --data-urlencode "filter[depth]=2"

Objects​

Storage object CRUD


Create a storage object​

POST/objects

Request Body​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "object",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"type": "object",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
},
  
  
"meta": {
  
  
  
"extension": "string",
  
  
  
"revisionId": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Responses​

The created storage object, possibly with meta.warnings.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "object",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
},
  
  
"meta": {
  
  
  
"extension": "string",
  
  
  
"revisionId": "string",
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.createObject({
  key: 'pages/about',
  content: {
    title: 'About',
    body: 'About this site.',
  },
});
sh
curl "$CONTENTIA_URL/objects" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "object",
      "id": "pages/about",
      "attributes": {
        "content": {
          "title": "About",
          "body": "About this site."
        }
      }
    }
  }'

Read a storage object​

GET/objects/{key}

Responses​

The storage object, possibly with meta.warnings.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "object",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
},
  
  
"meta": {
  
  
  
"extension": "string",
  
  
  
"revisionId": "string",
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.getObject('posts/hello-world');
sh
curl "$CONTENTIA_URL/objects/posts%2Fhello-world" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json"

Delete a storage object​

DELETE/objects/{key}

Responses​

Deletion confirmation, possibly with meta.warnings.

application/vnd.api+json
JSON
{
  
"meta": {
  
  
"deleted": true,
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.removeAtoms(['posts/hello-world']).collect();
sh
curl -X DELETE "$CONTENTIA_URL/objects/posts%2Fhello-world" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json"

Update a storage object​

PATCH/objects/{key}

Request Body​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "object",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"type": "object",
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
},
  
  
"meta": {
  
  
  
"extension": "string",
  
  
  
"revisionId": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
}
}

Responses​

The updated storage object, possibly with meta.warnings.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "object",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"content": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
},
  
  
"meta": {
  
  
  
"extension": "string",
  
  
  
"revisionId": "string",
  
  
  
"additionalProperties": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.updateObject({
  key: 'posts/hello-world',
  content: {
    title: 'Hello again',
    body: 'My first post, edited.',
  },
});
sh
curl -X PATCH "$CONTENTIA_URL/objects/posts%2Fhello-world" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "object",
      "id": "posts/hello-world",
      "attributes": {
        "content": {
          "title": "Hello again",
          "body": "My first post, edited."
        }
      }
    }
  }'

Folders​

Folder resources


Create a folder​

POST/atoms

Request Body​

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "folder",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"type": "folder"
  
  
}
  
}
}

Responses​

The created folder resource.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "folder",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.createFolder({
  key: 'pages',
});
sh
curl "$CONTENTIA_URL/atoms" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "data": {
      "type": "folder",
      "id": "pages",
      "attributes": {
        "type": "folder"
      }
    }
  }'

Read a folder​

GET/folders/{key}

Responses​

The folder resource, possibly with meta.warnings.

application/vnd.api+json
JSON
{
  
"data": {
  
  
"type": "folder",
  
  
"id": "string",
  
  
"attributes": {
  
  
  
"createdAt": "string",
  
  
  
"updatedAt": "string"
  
  
},
  
  
"links": {
  
  
  
"self": "string",
  
  
  
"additionalProperties": "string"
  
  
}
  
},
  
"meta": {
  
  
"warnings": [
  
  
  
{
  
  
  
  
"code": "string",
  
  
  
  
"status": "string",
  
  
  
  
"title": "string",
  
  
  
  
"detail": "string",
  
  
  
  
"source": {
  
  
  
  
  
"pointer": "string"
  
  
  
  
}
  
  
  
}
  
  
]
  
}
}
ts
await storage.getFolder('posts');
sh
curl "$CONTENTIA_URL/folders/posts" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json"

Operations​

JSON:API atomic operations extension


Atomic operations (add, update, remove)​

POST/operations

JSON:API atomic operations extension. Every operation is authorized before any runs, and one denial rejects the whole request. Adds and updates then run concurrently, while removes run one key per repository call, in request order; results keep request order. A failed add or update is omitted from atomic:results, and a failed remove keeps its slot as an errors entry. The operations are not transactional: when a remove call fails outright, the request fails and later removes are not attempted, while adds, updates and earlier removes may already have been applied.

Request Body​

application/vnd.api+json
JSON
{
  
"atomic:operations": [
  
  
{
  
  
  
"op": "add",
  
  
  
"data": {
  
  
  
  
"type": "object",
  
  
  
  
"id": "string",
  
  
  
  
"attributes": {
  
  
  
  
  
"type": "object",
  
  
  
  
  
"content": {
  
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
  
}
  
  
  
  
},
  
  
  
  
"meta": {
  
  
  
  
  
"extension": "string",
  
  
  
  
  
"revisionId": "string",
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
}
  
  
  
}
  
  
}
  
]
}

Responses​

One result per successful operation and per failed remove, in request order.

application/vnd.api+json
JSON
{
  
"atomic:results": [
  
  
{
  
  
  
"data": {
  
  
  
  
"type": "object",
  
  
  
  
"id": "string",
  
  
  
  
"attributes": {
  
  
  
  
  
"content": {
  
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
  
},
  
  
  
  
  
"createdAt": "string",
  
  
  
  
  
"updatedAt": "string"
  
  
  
  
},
  
  
  
  
"meta": {
  
  
  
  
  
"extension": "string",
  
  
  
  
  
"revisionId": "string",
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
},
  
  
  
  
"links": {
  
  
  
  
  
"self": "string",
  
  
  
  
  
"additionalProperties": "string"
  
  
  
  
}
  
  
  
},
  
  
  
"meta": {
  
  
  
  
"warnings": [
  
  
  
  
  
{
  
  
  
  
  
  
"code": "string",
  
  
  
  
  
  
"status": "string",
  
  
  
  
  
  
"title": "string",
  
  
  
  
  
  
"detail": "string",
  
  
  
  
  
  
"source": {
  
  
  
  
  
  
  
"pointer": "string"
  
  
  
  
  
  
}
  
  
  
  
  
}
  
  
  
  
]
  
  
  
}
  
  
}
  
]
}
sh
curl "$CONTENTIA_URL/operations" \
  -H "Authorization: Bearer $CONTENTIA_TOKEN" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/vnd.api+json" \
  -d '{
    "atomic:operations": [
      {
        "op": "add",
        "data": {
          "type": "object",
          "id": "pages/contact",
          "attributes": {
            "content": {
              "title": "Contact"
            }
          }
        }
      },
      {
        "op": "update",
        "data": {
          "type": "object",
          "id": "settings/site",
          "attributes": {
            "content": {
              "title": "My new site"
            }
          }
        }
      }
    ]
  }'