Using data buckets

After creating data buckets, you can use them through the data templating helpers or by directly referencing them in a route response or CRUD route.

 Using data helpers

 Retrieving data

Two helpers are available: data and dataRaw. They work in a similar way to the body and bodyRaw helpers.

They can be used anywhere templating helpers are supported: body editor, files, headers keys and values, etc., and allow you to partially reuse your data bucket content and compose dynamic responses body easily.

Both helpers support retrieving the data bucket by its unique ID or name. It also allows you to retrieve only part of the data bucket using an optional object path:

Copy
{{data 'ID_or_name' 'object.path'}}

Head over to the data helpers' documentation to see more examples.

 Setting data programmatically

A setData helper is available to set the content of a data bucket programmatically. It can be used anywhere templating helpers are supported.

This helper is useful when you want to update the content of a data bucket, push a new value to an array, delete a property, increment or decrement a number, or invert a boolean:

Copy
{{setData 'set' 'bucketNameOrId' 'path.to.property' 'newValue'}}
{{setData 'push' 'bucketNameOrId' 'path.to.array' 'newValue'}}
{{setData 'del' 'bucketNameOrId' 'path.to.property'}}
{{setData 'inc' 'bucketNameOrId' 'path.to.property' 2}}
{{setData 'dec' 'bucketNameOrId' 'path.to.property' 2}}
{{setData 'invert' 'bucketNameOrId' 'path.to.property'}}

Head over to the setData helper documentation to see more examples.

 Link a bucket to a CRUD route

When creating a CRUD route you must link a data bucket. This feature allows you to serve and manipulate the data bucket content depending on the CRUD operations. The CRUD routes follow usual REST conventions: GET /resources, POST /resources, PUT /resources/:id, DELETE /resources/:id, etc.

Head over to the dedicated CRUD routes documentation to learn more about this feature.

 Referencing a bucket in a route response

A data bucket can also be directly linked to a route response. Linking a data bucket will serve the generated data bucket content "as-is".

To link a data bucket to a route response, choose "Data" in the body selector and select your data bucket.

 Storing JSON schemas

A data bucket can also store a JSON schema. This schema can be used in the rules system, using the "valid JSON schema" operator to validate the targeted property using ajv.

To store a JSON schema in a data bucket, create a new data bucket and paste your JSON schema in the content editor. The schema must be a valid JSON object:

Copy
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" }
  },
  "required": ["name", "age"]
}

You will then be able to reference this schema in a rule's value field by using the data bucket's name or ID: mySchemaBucket.

A data bucket can also store multiple schemas on various properties:

Copy
{
  "name": {
    "type": "string"
  },
  "age": {
    "type": "number"
  }
}

To access a specific schema stored in a property, you can use the following syntax (using the object-path syntax) in the rule's value field: dataBucketNameOrId.propertyName. Example: mySchemasBucket.name or mySchemasBucket.age.