BranchAlias
BranchAlias
An alias is a stable name that points to one branch of a stack. Front-end code can request content through the alias, and you change the target branch without changing that code. The BranchAlias class manages aliases through the Content Management API (CMA). Use this class to
- assign an alias to a branch, or point an existing alias to another branch
- find which branch an alias points to
- list the aliases of a stack
- delete an alias
Call the branchAlias method of the Stack class to get an object.
Instance State
- Call stack.branchAlias() without a UID to list aliases with fetchAll.
- Call stack.branchAlias('<ALIAS_UID>') to work with one alias, for example createOrUpdate and fetch.
- Each form has only its own methods. A method of the other form is undefined, and calling it throws TypeError.
The Method Index below lists the full set for each form.
Warning stack.branchAlias('') returns the list form, because the SDK treats an empty string as no UID. Check the UID before you build the object.
Class-Level Notes
Results are branches.
- createOrUpdate, fetch and fetchAll resolve to Branch objects for the target branch, not to BranchAlias objects. Each has the methods of the Branch class for one branch.
Warning The delete method of a Branch object that this class returns deletes the target branch and its content, not the alias. To delete an alias, call delete on stack.branchAlias('<ALIAS_UID>').
Authentication.
- createOrUpdate and delete accept only an authtoken, as Assign an alias and Delete an alias state. Create the client with contentstack.client({ authtoken: '<AUTHTOKEN>' }).
- fetch and fetchAll accept a management token.
Headers.
- Every request sends the headers of this object, which start as a copy of the stack headers. Change them with addHeader, addHeaderDict and removeHeader.
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
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Assign or delete an alias with a management token | No | The API accepts only an authtoken for these requests. |
| Read the alias as its own object | No | The class returns Branch objects for the target branch. |
| Filter aliases with query() | No | Pass limit, skip and include_count to fetchAll. |
Method Index
List aliases. Available on stack.branchAlias().
| Method Name | Returns | Description |
|---|---|---|
| fetchAll | The aliases of the stack, each as a Branch object. | Lists the aliases of the stack. |
Work with one alias. Available on stack.branchAlias('<ALIAS_UID>').
| Method Name | Returns | Description |
|---|---|---|
| createOrUpdate | The target branch that the alias now points to. | Assigns the alias to a branch. |
| fetch | The branch that the alias points to. | Reads the target of the alias. |
| delete | The API response with a notice. | Deletes the alias. |
Set request headers. Available on both forms.
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same branch alias object, for chaining. | Adds one request header. |
| addHeaderDict | The same branch alias object, for chaining. | Adds several request headers. |
| removeHeader | The same branch alias object, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below points an alias to a branch with an authtoken, then reads the alias back.
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
await stack.branchAlias('<ALIAS_UID>').createOrUpdate('<BRANCH>')
const branch = await stack.branchAlias('<ALIAS_UID>').fetch()
console.log(branch.uid)
} 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 BranchAlias class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one header to the requests that this branch alias object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Header name, for example x-request-id. |
| value (required) | string | Header value to send. |
Returns: BranchAlias. The same branch alias 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.
- The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- Every request method of this object sends its headers.
- The Branch objects that createOrUpdate, fetch and fetchAll return start with the headers of this object.
- A key that the object already holds gets the new value.
Example
Basic usage: tag the requests of one branch alias object
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const target = stack.branchAlias('<ALIAS_UID>').addHeader('x-request-id', 'docs-123')
console.log(target.stackHeaders['x-request-id'])addHeaderDict
addHeaderDict adds several headers at once to the requests that this branch alias object sends.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: BranchAlias. The same branch alias 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.
- addHeaderDict copies every key of headerDict into the header map of this object. A key that the object already holds gets the new value.
- The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- Every request method of this object sends its headers.
- The Branch objects that createOrUpdate, fetch and fetchAll return start with the headers of this object.
Example
Basic usage: add a request ID and a trace ID
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const target = stack.branchAlias('<ALIAS_UID>').addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
console.log(target.stackHeaders['x-request-id'], target.stackHeaders['x-trace-id'])createOrUpdate
createOrUpdate assigns the alias whose UID you passed to stack.branchAlias('<ALIAS_UID>') to a target branch. It creates the alias when it does not exist yet, and points an existing alias to the new target. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| targetBranch (required) | string | UID of the branch the alias points to. |
Returns: Promise<Branch>. The target branch that the alias now points to.
Validation
- There is no client-side validation.
- createOrUpdate exists only on stack.branchAlias('<ALIAS_UID>'). On stack.branchAlias() 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.
- The API rejects the request when targetBranch is not a branch of the stack.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends PUT /v3/stacks/branch_aliases/{branch_alias_uid} with the body { branch_alias: { target_branch: targetBranch } }, as Assign an alias describes.
- The API accepts only an authtoken for this request, not a management token. Only stack owners, admins and developers can assign an alias.
- Resolves to a Branch object for the target branch, not to a BranchAlias object. Its uid is the UID of the target branch, and its delete method deletes that branch.
Example
Basic usage: point an alias to a branch
import contentstack from '@contentstack/management'
// Assigning an alias needs an authtoken, not a management token
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const branch = await stack.branchAlias('docs-test-alias').createOrUpdate('<BRANCH>')
console.log(branch.uid, branch.alias)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Edge case: move an existing alias to another branch
import contentstack from '@contentstack/management'
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
// The same call updates the target when the alias already exists
const branch = await stack.branchAlias('<ALIAS_UID>').createOrUpdate('main')
console.log(branch.uid)
} catch (error) {
console.error(error.errorMessage)
}delete
delete deletes the alias whose UID you passed to stack.branchAlias('<ALIAS_UID>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent with force=true. |
Returns: Promise<Response>. The API response with a notice.
Warning Deleting an alias removes it permanently. You cannot undo this. To use the alias again, assign it with the createOrUpdate method.
Validation
- There is no client-side validation.
- delete exists only on stack.branchAlias('<ALIAS_UID>'). On stack.branchAlias() 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/stacks/branch_aliases/{branch_alias_uid} with every key of param as a query parameter, as Delete an alias describes.
- delete always adds force=true to the query parameters, which the API requires to confirm the deletion. You do not need to pass it.
- The API accepts only an authtoken for this request, not a management token.
- Resolves to the response body as a plain object, with the API message in notice.
- delete on this object deletes the alias only. The delete method of a Branch object that fetch returns deletes the target branch instead.
Example
Basic usage: delete an alias
import contentstack from '@contentstack/management'
// Deleting an alias needs an authtoken, not a management token
const client = contentstack.client({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
const response = await stack.branchAlias('<ALIAS_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({ authtoken: '<AUTHTOKEN>' })
const stack = client.stack({ api_key: '<API_KEY>' })
try {
// The SDK sends force=true on every delete, so passing it changes nothing
const response = await stack.branchAlias('<ALIAS_UID>').delete({ force: true })
console.log(response.notice)
} catch (error) {
console.error(error.errorMessage)
}fetch
fetch retrieves the branch that the alias points to, for the alias whose UID you passed to stack.branchAlias('<ALIAS_UID>').
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters, sent as given. |
Returns: Promise<Branch>. The branch that the alias points to.
Validation
- There is no client-side validation.
- fetch exists only on stack.branchAlias('<ALIAS_UID>'). On stack.branchAlias() 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/stacks/branch_aliases/{branch_alias_uid} with every key of param as a query parameter, as Get a single alias describes. The API reference lists no query parameters for this request.
- Resolves to a Branch object for the target branch, not to a BranchAlias object. Its uid is the UID of the target branch, and its delete method deletes that branch.
Example
Basic usage: find the branch behind an alias
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const branch = await stack.branchAlias('<ALIAS_UID>').fetch()
console.log(branch.uid, branch.source, branch.alias)
} 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 {
// fetch sends every key of the object as a query parameter. The API lists none for this request.
const branch = await stack.branchAlias('<ALIAS_UID>').fetch({})
console.log(branch.uid)
} catch (error) {
console.error(error.errorMessage)
}fetchAll
fetchAll lists the aliases of the stack, each as the branch it points to.
| Name | Type | Description |
|---|---|---|
| param | object | Query parameters for the list request. |
| param.limit | number | Maximum number of aliases to return. |
| param.skip | number | Number of aliases to skip. |
| param.include_count | boolean | Adds the total count to the response. |
Returns: Promise<ContentstackCollection>. The aliases of the stack, each as a Branch object.
Validation
- There is no client-side validation.
- fetchAll exists only on stack.branchAlias(). On stack.branchAlias('<ALIAS_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 GET /v3/stacks/branch_aliases with every key of param as a query parameter, as Get all aliases describes.
- Resolves to a collection whose items are Branch objects, one for each alias, built from the target branch. With include_count: true, the collection also has count.
- The delete method of each item deletes the target branch, not the alias. To delete an alias, call delete on stack.branchAlias('<ALIAS_UID>').
- The client does not page through results. Use limit and skip to read more pages.
Example
Basic usage: list the aliases 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 aliases = await stack.branchAlias().fetchAll()
for (const branch of aliases.items) {
console.log(branch.alias, branch.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: read the first 10 aliases, 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>' })
try {
const aliases = await stack.branchAlias().fetchAll({ limit: 10, skip: 0, include_count: true })
console.log(aliases.count, aliases.items.length)
} catch (error) {
console.error(error.errorMessage)
}removeHeader
removeHeader removes one header from the requests that this branch alias object sends.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: BranchAlias. The same branch alias 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, and removeHeader returns the same object.
- An invalid value surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. removeHeader sends no request.
- The first header change on this object copies the headers that it inherited. The change then applies to this object only, not to the stack or to other objects that the same stack creates.
- Every request method of this object sends its headers.
- The Branch objects that createOrUpdate, fetch and fetchAll return start with the headers of this object.
- removeHeader can remove a header that the object inherited from the stack, such as branch. The stack and its other objects keep that header.
- Do not remove api_key. Without it, the API cannot tell which stack the request is for.
Example
Basic usage: drop a header that you added earlier
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const target = stack.branchAlias('<ALIAS_UID>')
.addHeaderDict({ 'x-request-id': 'docs-123', 'x-trace-id': 'trace-456' })
.removeHeader('x-trace-id')
console.log('x-trace-id' in target.stackHeaders) // false