Cloud Module

Appearance

Accessing Items ​

Items are individual pieces of data in your database. They can be anything, from articles, to IoT status checks. Learn more about Items.

The Item Object ​

Items don't have a predefined schema. The format depends completely on how you configured your collections 🪣 and fields in the Cloud Studio app 📟.

Relational Data

By default, the item object doesn't contain nested relational data. To retrieve nested data, see Relational Data and Field Parameters.

Access an Article Example

For this example, we'll use a fictional articles collection 🪣 with the following fields: id, status, title, body, featured_image, and author.

json
{
	"id": 1,
	"status": "published",
	"title": "Hello, world!",
	"body": "This is my first article",
	"featured_image": "768eabec-3c54-4110-a6bb-64b548116661",
	"author": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07"
}

Get Items ​

List all items that exist in the Cloud Studio app 📟.

Request ​

http
// If you use the `SEARCH` method than you can provide a [query object](query) as the body of your request.
GET /items/:collection
SEARCH /items/:collection
graphql
# POST /graphql
type Query {
	<collection>: [<collection>]
}

Query Parameters ​

Supports all global query parameters.

Relational Data

The Field Parameter is required to return nested relational data.

Response ​

An array of up to limit item objects. If no items are available, data will be an empty array.

Access a List of Articles Example

For this example, we'll access the articles from the collection without any specific query parameters.

http
GET /items/articles
SEARCH /items/articles
graphql
# For this example, we'll limit our query to the fields:
# `id`, `title`, and `author.first_name`.

# POST /graphql
query {
	articles {
		id
		title
		author {
			first_name
		}
	}
}

Get Item by ID ​

GET an item that exists in the Cloud Studio app 📟.

Request ​

http
GET /items/:collection/:id
graphql
# POST /graphql
type Query {
	<collection>_by_id(id: ID!): <collection>
}

# POST /graphql
type Query {
	<collection>_by_version(id: ID!, version String!): <collection_version>
}

Query Parameters ​

Supports all global query parameters.

Additionally, supports a version parameter to retrieve an item's state from a specific Content Version. The value corresponds to the key of the Content Version.

Response ​

Returns an item object if a valid primary key was provided.

Access Article 15 Example

For this example, we'll access an article by ID, which in this case is 15.

http
GET /items/articles/15
graphql
# POST /graphql
query {
	articles_by_id(id: 15) {
		id
		title
		body
	}
}

Access a Draft Version Example

For this example, we'll access the draft version of article 15:

http
GET /items/articles/15?version=draft
graphql
# POST /graphql
query {
	articles_by_version(id: 15, version: "draft") {
		id
		title
		body
	}
}

Get Singleton ​

List a singleton item in the Cloud Studio app 📟.

Request ​

http
GET /items/:collection
graphql
# POST /graphql
type Query {
	<collection>_by_version(version: String): <collection>
}

Info

The REST and GraphQL requests for singletons are the same as those used to Get Items but in contrast the response consists of a plain item object (the singleton) instead of an array of items.

Query Parameters ​

Supports all global query parameters.

Additionally, supports a version parameter to retrieve a singleton's state from a specific Content Version. The value corresponds to the key of the Content Version.

The Request Body ​

collection_name the name of the collection 🪣 is required.

Response ​

Returns an item object if a valid collection 🪣 name was provided.

Access the About Object Example

For this example, we'll access a singleton object called about.

http
GET /items/about
graphql
# POST /graphql
query {
	about {
		id
		content
	}
}

Access a Draft Version Example

For this example, we'll access the draft version of the about object .

http
GET /items/about?version=draft
graphql
# POST /graphql
query {
	about_by_version(version: "draft") {
		id
		content
	}
}

Create an Item ​

Create a new item in the given collection 🪣.

Request ​

http
// Provide an item object as the body of your request.
POST /items/:collection
graphql
# POST /graphql
type Mutation {
	create_<collection>_item(data: create_<collection>_input): <collection>
}

Query Parameters ​

Supports all global query parameters.

The Request Body ​

A partial item objects.

Relational Data

Relational data needs to be correctly nested to add new items successfully. Check out the relational data section for more information.

Response ​

Returns the item objects of the item that were created.

Create an Article Example

For this example, we'll create a new article item.

json
// POST /items/articles
{
	"title": "Hello world!",
	"body": "This is our first article"
}
graphql
# POST /graphql
mutation {
	create_articles_item(data: { title: "Hello world!", body: "This is our first article" }) {
		id
		title
	}
}

Create Multiple Items ​

Create new items in the given collection 🪣.

Request ​

http
// Provide an array of item object as the body of your request.
POST /items/:collection
graphql
# POST /graphql
type Mutation {
	create_<collection>_items(data: [create_<collection>_input]): [<collection>]
}

Query Parameters ​

Supports all global query parameters.

The Request Body ​

An array of partial item objects.

Response ​

Returns the item objects of the item that were created.

Create Multiple Articles Example

For this example, we'll create multiple articles at the same time.

json
// POST /items/articles
[
	{
		"title": "Hello world!",
		"body": "This is our first article"
	},
	{
		"title": "Hello again, world!",
		"body": "This is our second article"
	}
]
graphql
# POST /graphql
mutation {
	create_articles_items(
		data: [
			{ title: "Hello world!", body: "This is our first article" }
			{ title: "Hello again, world!", body: "This is our second article" }
		]
	) {
		id
		title
	}
}

Update an Item ​

Update an existing item.

Request ​

http
// Provide a partial item object as the body of your request.
PATCH /items/:collection/:id
graphql
# POST /graphql
type Mutation {
	update_<collection>_item(id: ID!, data: update_<collection>_input!): <collection>
}

Query Parameters ​

Supports all global query parameters.

The Request Body ​

A partial item object.

Response ​

Returns the item object of the item that was updated.

Update Article 15 Example

For this example, we'll update the article with ID 15.

json
// PATCH /items/articles/15
{
	"title": "An updated title"
}
graphql
# POST /graphql
mutation {
	update_articles_item(id: 15, data: { title: "An updated title" }) {
		id
		title
	}
}

Update Singleton ​

Update a singleton item.

Request ​

http
// Provide a partial item object as the body of your request.
PATCH /items/:collection
graphql
# POST /graphql
type Mutation {
	update_<collection>_items(data: [update_<collection>_input]): [<collection>]
}

Info

The REST and GraphQL requests for singletons are the same as those used to Update Multiple Items but in contrast the request should consist of the plain item object.

Query Parameters ​

Supports all global query parameters.

The Request Body ​

The name of the collection 🪣 collection_name is required and a partial item object.

Response ​

Returns an item object if a valid primary key was provided.

Update the About Object Example

For this example, we'll update a singleton object called about.

json
// PATCH /items/about
{
	"content": "Founded in 2023, this website is dedicated to..."
}
graphql
# POST /graphql
mutation {
	update_articles_items(data: { content: "Founded in 2023, this website is dedicated to..." }) {
		content
	}
}

Update Multiple Items ​

Update multiple items at the same time.

Request ​

http
// Provide a partial item object as the body of your request.
PATCH /items/:collection
graphql
# POST /graphql
```graphql
type Mutation {
	update_<collection>_items(ids: [ID!]!, data: [update_<collection>_input]): [<collection>]
}

Query Parameters ​

Supports all global query parameters.

The Request Body ​

Object containing data for the values to set, and either keys or query to select what items to update.

Response ​

Returns the item objects for the updated items.

Update Multiple Articles Example

For this example, we'll update multiple articles at the same time using the IDs 1 and 2.

json
// PATCH /items/articles
{
	"keys": [1, 2],
	"data": {
		"status": "published"
	}
}
graphql
# POST /graphql
mutation {
	update_articles_items(ids: [1, 2], data: { status: "published" }) {
		id
		status
	}
}

Delete an Item ​

Delete an existing item.

Request ​

http
DELETE /items/:collection/:id
graphql
# POST /graphql
type Mutation {
	delete_<collection>_item(id: ID!): delete_one
}

Response ​

Empty body.

Delete Article 15 Example

For this example, we'll delete an article with ID 15.

http
DELETE /items/articles/15
graphql
# POST /graphql
mutation {
	delete_articles_item(id: 15) {
		id
	}
}

Delete Multiple Items ​

Delete multiple existing items.

http
// Provide an array of item primary keys or an object containing either:
// `keys` or `query` as your request body.
DELETE /items/:collection
graphql
# POST /graphql
type Mutation {
	delete_<collection>_items(ids: [ID!]!): delete_many
}

Query Parameters ​

Supports all global query parameters.

The Request Body ​

An array of item primary keys or an object containing either keys or query to select what items to update.

Response ​

Empty body.

Delete Multiple Articles Example

For this example, we'll delete multiple articles with the IDs 15, 16 and 21.

json
// DELETE /items/articles

// Array of primary keys
[15, 16, 21]

// Object containing keys
{
	"keys": [15, 16, 21]
}

// Object containing query
{
	"query": {
		"filter": {
			"status": {
				"_eq": "draft"
			}
		}
	}
}
graphql
# POST /graphql
mutation {
	delete_articles_items(ids: [15, 16, 21]) {
		ids
	}
}