Help Center

Menu

Documents

Documents and collections are analogous to files and directories (respectively) on a file system.

Creating a new document

Make a PUT request to the document endpoint to create a new document with a user-specified ID. This example uses CURL:

curl \
    -X PUT \
    -H "Content-Type: application/json" \
    --silent \
    -d "$documentData" \
    -fS https://my-data-service.datastore.squiz.cloud/my-first-collection/documentID

Alternatively, Datastore provides a JavaScript SDK that aids in creating a document with a user-specified document ID: https://docs.squiz.net/datastore/latest/features/javascript-sdk.html

Editing a new document

Make a PATCH request to the document endpoint to edit an existing document. This example uses CURL:

curl \
    -X PATCH \
    -H "Content-Type: application/json" \
    --silent \
    -d "$documentData" \
    -fS https://my-data-service.datastore.squiz.cloud/my-first-collection/documentID

Alternatively, Datastore provides a JavaScript SDK that aids in updating documents: https://docs.squiz.net/datastore/latest/features/javascript-sdk.html

Getting a document

Make a GET request to the document endpoint to get a specific document. This example uses CURL:

curl \
    -X GET \
    -H "Content-Type: application/json" \
    --silent \
    -fS https://my-data-service.datastore.squiz.cloud/my-first-collection/documentID

Alternatively, Datastore provides a JavaScript SDK that aids in getting a document: https://docs.squiz.net/datastore/latest/features/javascript-sdk.html

Deleting a document

Make a DELETE request to the document endpoint to delete a specific document. This example uses CURL:

curl \
    -X DELETE \
    -H "Content-Type: application/json" \
    --silent \
    -fS https://my-data-service.datastore.squiz.cloud/my-first-collection/documentID

Alternatively, Datastore provides a JavaScript SDK that aids in deleting a document: https://docs.squiz.net/datastore/latest/features/javascript-sdk.html

Response codes

Document requests can return the following HTTP codes:

Table 1. Success codes

HTTP Method

HTTP code

Notes

GET

200 OK

Returned when the document or collection exists.

PUT

201 Created

Returned when the document currently exists at that URI.

200 OK

Returned if the document exists, has now been replaced, and the API description defines response data.

204 No Content

Returned if the document exists, has now been replaced, and the API description does not define any response data.

PATCH

200 OK

Returned if the document was updated and the API description defines response data.

204 No Content

Returned if the document was updated and the API description does not define any response data.

DELETE

204 No Content

Returned if the document was deleted.
Table 2. Error codes

Code

Description

JSON

400 Bad Request

Returned when a POST, PATCH, or PUT request contains invalid or missing property data. A 400 Bad Request error object contains an additional property called invalid-params, which lists the validation error for each invalid or missing document property.

Each property validation error is an object containing a name and reason property. The name is the name of the document property that was invalid or missing. The reason is a user-friendly error message describing the validation error.

 
{
   "title": "JSON does not validate.",
   "status ": "400",
   "invalid-params": [
      {
           "name": "comment",
           "reason": "Comment length must not exceed 5000 characters"
      }
   ]
}

401 Unauthorized

Returned when an ACL protects a request, but no valid JWT was provided with the request. This can be caused by no JWT being sent, or the supplied JWT was not signed with the correct secret key and cannot be decoded.

Datastore returns 401 Unauthorized instead of 403 Forbidden to indicate that there was no user data against which to compare.

So it is unknown if the current user is allowed to make the request.

 
{
   "title": "Unauthorized",
   "status": "401"
}

403 Forbidden

Returned when an ACL rule failed for a request. No additional information about what rule failed is supplied in the error object to avoid information leakage.

 
{
   "title": "Forbidden",
   "status": "403"
}

404 Not found

Returned when the requested document or collection does not exist. The title of the error message indicates the requested resource type.

 
{
   "title": "Document not found",
   "status": "404"
}

{
   "title": "Collection not found",
   "status": "404"
}

405 Method Not Allowed

Returned when the HTTP method is not defined inside the API description document for the requested path.

 
{
   "title": "Method Not Allowed",
   "status": "405"
}

Document properties

Specify document properties in the properties section of a JSON Schema file. Alternatively, these properties can also be specified in the OpenAPI specification itself.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "string": {
            "type": "string"
        },
        "datetime": {
            "type": "string",
            "format": "date-time"
        },
        "integer": {
            "type": "integer"
        },
        "number": {
            "type": "number"
        },
        "boolean": {
            "type": "boolean"
        },
        "arrayString": {
            "type": "array",
            "items": {
            "type": "string"
            }
        },
        "arrayDatetime": {
            "type": "array",
            "items": {
                "type": "string",
                "format": "date-time"
            }
        },
        "arrayBoolean": {
            "type": "array",
            "items": {
                "type": "boolean"
            }
        },
        "arrayNumber": {
            "type": "array",
            "items": {
                "type": "number"
            }
        },
        "arrayInteger": {
            "type": "array",
            "items": {
                "type": "integer"
            }
        }
    }
}

Default and null values for properties

If the property requires a default value, the default key can be added to its property definition.

…
"string": {
     "type": "string",
     "default": "my default"
 }
…

If a property needs to support undefined values (null), the null type can be added to the type definition.

…
"string": {
     "type": [“null”, "string"],
     "default": "my default"
 }
…

Source properties

To have Datastore return one of its source properties, you define the property in the blueprint using the x-datastore-source key. The table below shows a complete list of source properties and their accepted values.

Source Property

Description

Settable

Default value

$id

The document ID

Yes - in document URL path for a PUT request.

UUID or user-specified ID of the document.

$createdDatetime

The DateTime the document was initially created.

No - Datastore sets this automatically.

Datetime the document was created.

$updatedDatetime

The DateTime the document was last updated, on initial create this value is the same as $createdDatetime.

No - Datastore sets this automatically.

Datetime the document was updated.

$extends

The path to the document that this document extends, if any.

Yes - when specified as a property in the blueprint, this value accepts the string path to another document.

Empty string.

$extendsAll

An ordered array of document paths that this extends. The first element is the immediate document path that this document extends.

No - Datastore sets this automatically.

Empty array

$extendedBy

The document paths as an alphabetically sorted array that immediately extend this document.

No - Datastore sets this automatically.

Empty array

$extendedByAll

The document paths as an alphabetically sorted array that extend this document either immediately or not.

No - Datastore sets this automatically.

Empty array.

 
…
"id": {
      "x-datastore-source": "document.$id"
},
"created": {
    "x-datastore-source": "document.$createdDatetime"
},
"updated": {
    "x-datastore-source": "document.$updatedDatetime"
},
"extends": {
    "x-datastore-source": "document.$extends"
},
"extendsAll": {
    "x-datastore-source": "document.$extendsAll"
},
"extendedBy": {
     "x-datastore-source": "document.$extendedBy"
},
"extendedByAll": {
    "x-datastore-source": "document.$extendedByAll"
},
…