Labels

View as Markdown

Labels

A label groups content types that work together, such as the content types of one website section. The Label class manages the labels of a stack through the Content Management API (CMA). Use this class to

  • add a label and assign content types to it
  • list the labels of a stack, or read one by its UID
  • rename a label, nest it under a parent label, or change its content types
  • delete a label

Call the label method of the Stack class to get an object.

Instance State

  • Call stack.label() without a UID to work with the labels of the stack, for example create and query.
  • Call stack.label('<LABEL_UID>') to work with one label, for example fetch and delete.
  • Each form has only its own methods. A method of the other form is undefined, and calling it throws TypeError.
  • The objects that create, fetch, update and query().find() return are the single-label form.

The Method Index below lists the full set for each form.

Warning stack.label('') returns the collection form, because the SDK treats an empty string as no UID. Check the UID before you build the object.

Class-Level Notes

Branch scoping.

  • When you create the stack with branch_uid, every request from this class sends the branch header, and the API works with the labels of that branch.

Headers.

  • Every request sends the headers of this object. The object shares the header map of the stack until you change its headers with addHeader, addHeaderDict or removeHeader. The first change gives the object its own copy.

Rate limiting and retry.

  • This SDK automatically retries on 429 with configurable delay and attempt limits.

Additional Resource For more information on the retry options and their defaults, refer to the Contentstack documentation.

Capability Matrix

CapabilitySupportedNotes / Alternative
Update fields without fetching firstNoupdate sends the properties of the object. Call fetch, change the result, then call update

Method Index

Work with the labels of a stack. Available on stack.label().

Method NameReturnsDescription
createThe new label.Adds a label to the stack.
queryA query for labels, sent when you call find(), findOne() or count().Lists the labels of the stack.

Work with one label. Available on stack.label('<LABEL_UID>').

Method NameReturnsDescription
fetchThe requested label.Reads one label.
updateThe updated label.Saves changes to the label.
deleteThe API response with a notice.Deletes the label.

Set request headers. Available on both forms.

Method NameReturnsDescription
addHeaderThe same label object, for chaining.Adds one request header.
addHeaderDictThe same label object, for chaining.Adds several request headers.
removeHeaderThe same label object, for chaining.Removes one request header.

Class-Level Snippet

The snippet below adds a label for two content types, then lists every label of the stack.

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const label = await stack.label().create({
    label: { name: 'docs-test-blog', content_types: ['<CONTENT_TYPE_UID>', 'author'] }
  })
  console.log(label.uid)

  const labels = await stack.label().query().find()
  labels.items.forEach((item) => console.log(item.uid, item.name))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

Methods

Each method of the Label class has its own section below, with its parameters, validation rules, behavior, and examples.

addHeader

addHeader adds one header to every request that this label object sends.

NameTypeDescription
key (required)string

Header name, for example x-request-id.

Default: Not applicable
value (required)string

Header value to send.

Default: Not applicable

Returns: Label. The same label object, for chaining.

Validation

  • There is no client-side validation. A null or undefined key leaves the headers unchanged, and addHeader returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeader sends no request.
  • Until its first header change, this object shares the header map of the stack. The first change copies that map, so the header applies to this object only, not to the stack or to other objects of the same stack.
  • Every request method of this object sends its headers. A key that the object already holds gets the new value.
  • query copies the headers of this object when you call it. Add the header first, then call query.

Example

Basic usage: tag the requests of one label object

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const label = stack.label('<LABEL_UID>').addHeader('x-request-id', 'docs-123')
// Every request this object sends from now on carries the header
console.log(label.stackHeaders['x-request-id'])

addHeaderDict

addHeaderDict adds several headers to every request that this label object sends.

NameTypeDescription
headerDict (required)object

Header names and values to add.

Default: Not applicable

Returns: Label. The same label object, for chaining.

Validation

  • There is no client-side validation. A null value, or a value that is not an object, leaves the headers unchanged, and addHeaderDict returns the same object.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. addHeaderDict sends no request.
  • Copies every key of headerDict into the headers of this object. A key that the object already holds gets the new value.
  • The first header change on this object copies the header map that it shares with the stack. The change then applies to this object only.

Example

Basic usage: send two extra headers from one label object

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

const label = stack.label('<LABEL_UID>').addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'docs-456' })
// fetch, update and delete on this object send both headers
console.log(label.stackHeaders)

create

create adds a label to the stack and assigns content types to it.

NameTypeDescription
data (required)object

Request body with the label under label.

Default: Not applicable
data.label.name (required)string

Name of the label.

Default: Not applicable
data.label.content_types (required)string[]

UIDs of the content types in the label.

Default: Not applicable
data.label.parentstring[]

UID of the parent label.

Default: API default
paramobject

Query parameters, sent as given.

Default: undefined (sends no query parameters)
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Label>. The new label.

Validation

  • There is no client-side validation. create sends data as the JSON body as it is.
  • create exists only on stack.label(). On stack.label('<LABEL_UID>') it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends POST /v3/labels with data as the body and every key of param as a query parameter, as Add label describes.
  • Resolves to a new Label object that holds the created label, with fetch, update and delete. When the API answers with an empty body, it resolves to { status, statusText } instead.

Example

Basic usage: add a label for one content type

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const label = await stack.label().create({
    label: { name: 'docs-test-blog', content_types: ['<CONTENT_TYPE_UID>'] }
  })
  console.log(label.uid)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: add a child label on a branch

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

try {
  const label = await stack.label().create({
    label: {
      name: 'docs-test-blog-authors',
      content_types: ['<CONTENT_TYPE_UID>'],
      parent: ['<LABEL_UID>']
    }
  }, { include_branch: true })
  console.log(label.uid, label.parent, label._branch)
} catch (error) {
  console.error(error.errorMessage)
}

delete

delete removes the label whose UID you passed to stack.label('<LABEL_UID>') from the stack.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}

Returns: Promise<Response>. The API response with a notice.

Warning A successful delete removes the label permanently, and you cannot undo it.

Validation

  • There is no client-side validation.
  • delete exists only on stack.label('<LABEL_UID>') and on the Label objects that requests return. On stack.label() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends DELETE /v3/labels/{label_uid} with every key of param as a query parameter, as Delete label describes. The API reference lists no query parameters for this request.
  • Resolves to the response body, which carries notice. When the API answers with an empty body, it resolves to { status, statusText } instead.

Example

Basic usage: delete a label

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const response = await stack.label('<LABEL_UID>').delete()
  console.log(response.notice)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: pass query parameters

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  // delete sends every key of the object as a query parameter. The API lists none for this request.
  const response = await stack.label('<LABEL_UID>').delete({})
  console.log(response.notice)
} catch (error) {
  console.error(error.errorMessage)
}

fetch

fetch retrieves the label whose UID you passed to stack.label('<LABEL_UID>').

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Label>. The requested label.

Validation

  • There is no client-side validation.
  • fetch exists only on stack.label('<LABEL_UID>') and on the Label objects that requests return. On stack.label() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends GET /v3/labels/{label_uid} with every key of param as a query parameter, as Get a single label describes.
  • Resolves to a new Label object that the SDK builds from the label key of the response, with fetch, update and delete.

Example

Basic usage: read one label

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const label = await stack.label('<LABEL_UID>').fetch()
  console.log(label.name, label.content_types)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: read a label of a branch with its branch UID

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

try {
  const label = await stack.label('<LABEL_UID>').fetch({ include_branch: true })
  console.log(label.name, label._branch)
} catch (error) {
  console.error(error.errorMessage)
}

query

query builds a request that lists the labels of the stack. It sends nothing until you call find(), findOne() or count() on the result.

NameTypeDescription
paramsobject

Query parameters for the list request.

Default: {}
params.queryobject

Filter condition, sent as JSON, for example by name.

Default: API default
params.include_countboolean

Adds the total label count to the response.

Default: API default
params.include_branchboolean

Adds the _branch key to each item.

Default: API default

Returns: Query. A query for labels, sent when you call find(), findOne() or count().

Validation

  • There is no client-side validation.
  • query exists only on stack.label(). On stack.label('<LABEL_UID>') it is undefined, and calling it throws TypeError.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • query sends no request. find(), findOne() and count() on the returned object each send GET /v3/labels, as Get all labels describes.
  • The SDK sends params.query as a JSON string in the query parameter, and every other key of params as its own query parameter.
  • The returned object copies the headers of this label object when you call query. A header that you add to the label object later does not reach it.
  • find() resolves to a collection whose items are Label objects, each with fetch, update and delete. With include_count: true, the collection also has count. See the find method of the Query class for the collection.

Example

Basic usage: list the labels of a stack

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const result = await stack.label().query().find()
  result.items.forEach((label) => console.log(label.uid, label.name))
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: find a label by name on a branch, with the total count

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

try {
  const result = await stack.label()
    .query({ query: { name: 'docs-test-blog' }, include_count: true, include_branch: true })
    .find()
  console.log(result.count, result.items.map((label) => label._branch))
} catch (error) {
  console.error(error.errorMessage)
}

removeHeader

removeHeader removes one header from the requests that this label object sends.

NameTypeDescription
key (required)string

Name of the header to remove.

Default: Not applicable

Returns: Label. The same label object, for chaining.

Validation

  • There is no client-side validation. A null or undefined key, or a key that the object does not hold, leaves the headers unchanged.
  • An invalid value surfaces as a rejected promise from the request method you call next.

Behavior

  • Client-side only. removeHeader sends no request.
  • Removing a header that the object shares with the stack first copies the shared map, so the stack and other objects keep the header.
  • The SDK adds some headers at request time, for example the authorization header of the client. removeHeader cannot remove those.

Example

Basic usage: send requests from one label object without the branch header

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

const label = stack.label('<LABEL_UID>').removeHeader('branch')
// This object now works with the default branch
console.log(label.stackHeaders.branch)

update

update saves your changes to the properties of this label object, such as its name, parent or content types.

NameTypeDescription
paramobject

Query parameters, sent as given.

Default: {}
param.include_branchboolean

Adds the _branch key to the response.

Default: API default

Returns: Promise<Label>. The updated label.

Validation

  • There is no client-side validation.
  • update exists only on stack.label('<LABEL_UID>') and on the Label objects that requests return. On stack.label() it is undefined, and calling it throws TypeError.
  • The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • Sends PUT /v3/labels/{label_uid} with every key of param as a query parameter, as Update label describes.
  • The body is { label: { ... } }, built from the properties of this object. The SDK leaves out uid, created_at, created_by, updated_at, updated_by, deleted_at, org_uid, api_key and its own internal properties.
  • Call fetch first and change the result. An object from stack.label('<LABEL_UID>') holds only the UID, so update on it sends an empty label object.
  • Resolves to a new Label object that the SDK builds from the label key of the response.

Example

Basic usage: rename a label

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })

try {
  const label = await stack.label('<LABEL_UID>').fetch()
  label.name = 'docs-test-articles'
  const updated = await label.update()
  console.log(updated.name)
} catch (error) {
  // The API rejected the request. The error carries status, errorCode, errorMessage and errors.
  console.error(error.status, error.errorCode, error.errorMessage)
}

All parameters: add a content type to a label on a branch

import contentstack from '@contentstack/management'

const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })

try {
  const label = await stack.label('<LABEL_UID>').fetch()
  label.content_types = [...label.content_types, '<CONTENT_TYPE_UID>']
  const updated = await label.update({ include_branch: true })
  console.log(updated.content_types, updated._branch)
} catch (error) {
  console.error(error.errorMessage)
}