Collections

Collections and documents are analogous to directories and files (respectively) on a file system.

Adding a document to a collection

Adding documents to a collection is done by making a POST request to the collections endpoint. This example uses CURL:

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

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

Getting documents in a collection

You get documents in a collection by making a GET request to the collections endpoint. This example uses CURL:

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

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

Response codes

Collection requests return the following HTTP response code:

Table 1. Success codes

HTTP Method

HTTP code

Notes

GET

200 OK

Returned when the document or collection exists.

POST

201 Created

Returned when posting to a collection to create a document inside that collection.

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 no that there was 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 has not been defined inside the API description document for the requested path.

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