Data Items API: Sample Use Cases & Flows

This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful starting point as you plan your implementation.

Populate a tutorials collection with content

You can use the Data Items API to programmatically add content to an existing collection.

This flow uses bulk operations to efficiently add multiple tutorials into an existing tutorials collection.

To populate the tutorials collection:

1. Call Bulk Insert Data Items with dataCollectionId set to tutorials. For each dataItem, include fields as structured in the data collection to be inserted. For reference fields like category and author, provide the ID of the referenced item from their respective collections.
2. Check the results array in the response to confirm each item inserted successfully. If any items fail, the itemMetadata.error property of the corresponding entry contains details about the error.

Query tutorials by category

You can retrieve tutorials from an existing tutorials collection filtered by category and sorted by publish date. This is useful for displaying a list of tutorials in a specific topic area.

To query tutorials by category:

1. Call Query Data Items with dataCollectionId set to tutorials and filter by category sorted by publishDate.

Get tutorial statistics by category

You can calculate aggregate statistics across tutorials in an existing tutorials collection, such as the total number of tutorials and average reading time per category. This is useful for analytics dashboards or category overview pages.

To aggregate tutorial data:

1. Call Aggregate Data Items with dataCollectionId set to tutorials.
2. In the aggregation object, set groupingFields to ["category"] to group results by category.
3. In the operations array, add aggregation operations:
   • Add an operation with resultFieldName set to totalTutorials and itemCount set to an empty object to count tutorials per category.
   • Add an operation with resultFieldName set to avgReadingTime, average.itemFieldName set to estimatedTime to calculate the average reading time.
4. The response contains 1 result per category with the calculated totalTutorials and avgReadingTime values.