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.
import { jsonSerializer } from 'contentia/serializers/json';
import { FileSystemStorageRepository } from 'contentia/storage/fs';
export const storage = new FileSystemStorageRepository('./content', { json: jsonSerializer }, 'json');export CONTENTIA_URL=https://cms.example.com/storage
export CONTENTIA_TOKEN=your-api-tokenKeys 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.
Underlying storage repository capabilities
/capabilitiesResolved from the repository on every request, so a swapped-out backend is reflected immediately.
Responses
The storage-capabilities resource.
/capabilitiesawait storage.getCapabilities();
curl "$CONTENTIA_URL/capabilities" \
-H "Authorization: Bearer $CONTENTIA_TOKEN" \
-H "Accept: application/vnd.api+json"
List atoms in the root folder
/atomsParameters
Query Parameters
Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.
1Items 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.
1Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.
0Maximum 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.
1Forward 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).
Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Recursion depth for the folder walk. Values that are not integers >= 1 fall back to 1.
11Responses
Atoms in the folder, with pagination links and optional meta.page.total / meta.warnings.
/atomsawait storage.listAtoms('', {
depth: 1,
pagination: { perPage: 100 },
}).collect();
curl "$CONTENTIA_URL/atoms" \
-H "Authorization: Bearer $CONTENTIA_TOKEN" \
-H "Accept: application/vnd.api+json"
List atoms in a folder
/atoms/{key}Parameters
Query Parameters
Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.
1Items 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.
1Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.
0Maximum 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.
1Forward 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).
Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Recursion depth for the folder walk. Values that are not integers >= 1 fall back to 1.
11Responses
Atoms in the folder, with pagination links and optional meta.page.total / meta.warnings.
/atoms/{key}await storage.listAtoms('posts', {
depth: 2,
pagination: { perPage: 100 },
}).collect();
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)
/atom/{key}Responses
The object or folder at the key, possibly with meta.warnings.
/atom/{key}await storage.getAtom('posts/hello-world');
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
/atom-summariesParameters
Query Parameters
Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.
1Items 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.
1Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.
0Maximum 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.
1Forward 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).
Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Recursion depth for the folder walk. Values that are not integers >= 1 fall back to 1.
11Responses
Atom summaries in the folder, with pagination links and optional meta.page.total / meta.warnings.
/atom-summariesawait storage.listAtomSummaries('', {
depth: 1,
pagination: { perPage: 100 },
}).collect();
curl "$CONTENTIA_URL/atom-summaries" \
-H "Authorization: Bearer $CONTENTIA_TOKEN" \
-H "Accept: application/vnd.api+json"
List atom summaries (lightweight listing) in a folder
/atom-summaries/{key}Parameters
Query Parameters
Page number for page-based pagination (1-based). Defaults to 1 when no pagination key is present.
1Items 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.
1Zero-based item offset for offset-based pagination. Without page[limit], the backend picks how many items to return.
0Maximum 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.
1Forward 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).
Backward cursor. Rejected with 400 when the backend does not declare cursor pagination (consult GET /capabilities, pagination.styles.cursor).
Recursion depth for the folder walk. Values that are not integers >= 1 fall back to 1.
11Responses
Atom summaries in the folder, with pagination links and optional meta.page.total / meta.warnings.
/atom-summaries/{key}await storage.listAtomSummaries('posts', {
depth: 2,
pagination: { perPage: 100 },
}).collect();
curl -G "$CONTENTIA_URL/atom-summaries/posts" \
-H "Authorization: Bearer $CONTENTIA_TOKEN" \
-H "Accept: application/vnd.api+json" \
--data-urlencode "filter[depth]=2"
Create a storage object
/objectsRequest Body
Responses
The created storage object, possibly with meta.warnings.
/objectsawait storage.createObject({
key: 'pages/about',
content: {
title: 'About',
body: 'About this site.',
},
});
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
/objects/{key}Responses
The storage object, possibly with meta.warnings.
/objects/{key}await storage.getObject('posts/hello-world');
curl "$CONTENTIA_URL/objects/posts%2Fhello-world" \
-H "Authorization: Bearer $CONTENTIA_TOKEN" \
-H "Accept: application/vnd.api+json"
Delete a storage object
/objects/{key}Responses
Deletion confirmation, possibly with meta.warnings.
/objects/{key}await storage.removeAtoms(['posts/hello-world']).collect();
curl -X DELETE "$CONTENTIA_URL/objects/posts%2Fhello-world" \
-H "Authorization: Bearer $CONTENTIA_TOKEN" \
-H "Accept: application/vnd.api+json"
Update a storage object
/objects/{key}Request Body
Responses
The updated storage object, possibly with meta.warnings.
/objects/{key}await storage.updateObject({
key: 'posts/hello-world',
content: {
title: 'Hello again',
body: 'My first post, edited.',
},
});
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."
}
}
}
}'
Create a folder
/atomsRequest Body
Responses
The created folder resource.
/atomsawait storage.createFolder({
key: 'pages',
});
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
/folders/{key}Responses
The folder resource, possibly with meta.warnings.
/folders/{key}await storage.getFolder('posts');
curl "$CONTENTIA_URL/folders/posts" \
-H "Authorization: Bearer $CONTENTIA_TOKEN" \
-H "Accept: application/vnd.api+json"
Atomic operations (add, update, remove)
/operationsJSON: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
Responses
One result per successful operation and per failed remove, in request order.
/operationscurl "$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"
}
}
}
}
]
}'