Version

View as Markdown

Version

The Version class lists the versions of one entry or asset, and sets or removes the name of one version.

When to Use This Class: Use this class when your code marks a milestone version with a name, for example the version that went live at launch.

Conceptual Role: Acts as the Content Management API (CMA) client for the versions endpoints of entries and assets. Call the Version method of Entry or the Version method of Asset to get an instance.

Returns: Version. A handle for version operations.

Instance State

The version number you pass to Version() decides which methods you can call on the instance:

  • Call .Version() without a number to list all versions, with GetAll or GetAllAsync.
  • Call .Version(2) to work with version 2, for example SetName or Delete.

If you call a method from the other group, it throws InvalidOperationException before any request leaves the SDK. The Method Index below lists every method in each group.

Warning Set the version number only through .Version(<number>). The instance also has a settable Number property, but the SDK builds the request path when you call .Version(). Setting Number later changes which methods the SDK allows without changing which version the request targets.

Class-Level Notes

Entries and assets.

  • The same class serves both. On an entry, the request path starts with /content_types/<CONTENT_TYPE_UID>/entries/<ENTRY_UID>, and the request body uses the entry key.
  • On an asset, the request path starts with /assets/<ASSET_UID>, and the request body uses the asset key.
  • The class also has a public constructor. Use the Version methods of Entry and Asset instead, because they build the request path for you.

Authentication.

  • The Version methods do not check for an authtoken or a management token. A request without one reaches the API, which rejects it. The Stack that created the entry or asset already ran that check.
  • The SDK sends the client's authtoken, or the stack's management token when the Stack has one.

Errors.

  • The SDK throws ContentstackErrorException when the API returns an error status. Read StatusCode, ErrorCode, ErrorMessage, and Errors on the exception to see what the API rejected.

Rate Limiting & Retry.

  • This SDK automatically retries a request that returns 429, 500, 502, 503, or 504, with configurable delay and attempt limits.

Additional Resources Refer to Retry Mechanism to configure retries, and Content Management API Errors for the error codes the API returns.

Async methods.

  • An async method runs its client-side checks when you call it, before it returns a task. An API rejection surfaces when you await the task.

Capability Matrix

CapabilitySupportedNotes / Alternative
Name or list the versions of an entry variantNoEntryVariant has no Version method.
Read the content of an earlier entry versionThrough FetchCall the Fetch method of Entry with version in collection.

Method Index

List all versions. Available on .Version() when you pass no number.

Method NameReturnsDescription
GetAllThe API response with the version details.Lists the versions of the entry or asset.
GetAllAsyncThe API response with the version details.Lists the versions asynchronously.

Name one version. Available on .Version(<number>).

Method NameReturnsDescription
SetNameThe API response with the named version.Assigns a name to the version.
SetNameAsyncThe API response with the named version.Assigns a name asynchronously.
DeleteAn API response with no body.Removes the name of the version.
DeleteAsyncAn API response with no body.Removes the name asynchronously.

Class-Level Snippet

The snippet below names version 2 of an entry and then lists only the named versions.

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Entry entry = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>");

try
{
    await entry.Version(2).SetNameAsync("Launch copy");

    ParameterCollection collection = new ParameterCollection();
    collection.Add("named", true);
    ContentstackResponse response = await entry.Version().GetAllAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects a request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

Methods

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

Delete

Delete removes the name of the version whose number you passed to Version(). The version itself stays.

NameTypeDescription
localestring?

Accepted but not sent. Has no effect.

Default: null

Returns: ContentstackResponse. An API response with no body.

Validation

  • Throws InvalidOperationException if the instance has no version number, because Delete acts on one version. Call .Version(<number>).
  • Throws ContentstackErrorException when the API rejects the request.

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

Behavior

  • Sends one DELETE request to <ENTRY_OR_ASSET_PATH>/versions/<VERSION_NUMBER>/name, with an empty entry object as the body. On an asset, the body key is asset.
  • locale has no effect. The SDK does not send it, and the Content Management API (CMA) reference lists no locale parameter for this request.
  • The API resets the name of the version to its version number. The content of the version does not change. See Delete Version Name of Entry and Delete Version Name of Asset.
  • The CMA reference lists status 204 for this request, so the response has no body. Read StatusCode, because OpenJsonObjectResponse() throws JsonException on an empty body.

Warning Deleting a version name removes the name you assigned. Neither the SDK nor the API keeps the old name, so record it first if you need it later.

Example

Basic usage: remove the name of an entry version

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Version(2).Delete();
    Console.WriteLine(response.StatusCode);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: pass a locale, which the SDK does not send

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    // The locale argument does not reach the API.
    ContentstackResponse response = client.Stack("<API_KEY>").Asset("<ASSET_UID>").Version(1).Delete("<LOCALE_CODE>");
    Console.WriteLine(response.StatusCode);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

DeleteAsync

DeleteAsync removes the name of the version whose number you passed to Version(), without blocking the calling thread.

NameTypeDescription
localestring?

Accepted but not sent. Has no effect.

Default: null

Returns: Task<ContentstackResponse>. An API response with no body.

Validation

  • Throws InvalidOperationException if the instance has no version number, because DeleteAsync acts on one version. The SDK throws it when you call DeleteAsync, before it returns a task.
  • Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.

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

Behavior

Warning Deleting a version name removes the name you assigned. Neither the SDK nor the API keeps the old name, so record it first if you need it later.

Example

Basic usage: remove the name of an entry version

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Version(2).DeleteAsync();
    Console.WriteLine(response.StatusCode);
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: pass a locale, which the SDK does not send

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Asset("<ASSET_UID>").Version(1).DeleteAsync("<LOCALE_CODE>");
    Console.WriteLine(response.StatusCode);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

GetAll

GetAll lists the versions of the entry or asset that created the instance.

NameTypeDescription
collectionParameterCollection?

Query parameters, for example named or locale.

Default: null

Returns: ContentstackResponse. The API response with the version details.

Validation

  • Throws InvalidOperationException if the instance has a version number, because GetAll lists every version. Call .Version() with no number.
  • Throws ContentstackErrorException when the API rejects the request.

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

Behavior

  • Sends one GET request to <ENTRY_OR_ASSET_PATH>/versions, with the entries of collection as query parameters.
  • The Content Management API (CMA) reference lists the query parameters below. See Get Details of All Versions of an Entry and Get Details of All Versions of an Asset.
    • named: only the versions that have a name.
    • include_count: the total number of versions.
    • include_updated_at and include_updated_by: when and by whom each version changed.
    • locale: the locale of the entry versions. The entry request lists it, and the asset request does not.
  • The _version_name field appears in the response only for a version that has a name.
  • Returns the raw API response.

Example

Basic usage: list the versions of an entry

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Version().GetAll();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: list the named versions of an entry in one locale

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("named", true);
collection.Add("include_count", true);
collection.Add("include_updated_by", true);
collection.Add("locale", "<LOCALE_CODE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Version().GetAll(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Management token: list the versions of an asset

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient();

try
{
    ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").Asset("<ASSET_UID>").Version().GetAll();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

GetAllAsync

GetAllAsync lists the versions of the entry or asset that created the instance, without blocking the calling thread.

NameTypeDescription
collectionParameterCollection?

Query parameters, for example named or locale.

Default: null

Returns: Task<ContentstackResponse>. The API response with the version details.

Validation

  • Throws InvalidOperationException if the instance has a version number, because GetAllAsync lists every version. The SDK throws it when you call GetAllAsync, before it returns a task.
  • Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.

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

Behavior

Example

Basic usage: list the versions of an entry

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Version().GetAllAsync();
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: count the named versions of an asset

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

ParameterCollection collection = new ParameterCollection();
collection.Add("named", true);
collection.Add("include_count", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Asset("<ASSET_UID>").Version().GetAllAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse()["count"]);
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

SetName

SetName assigns a name to the version whose number you passed to Version().

NameTypeDescription
name (required)string

Name to assign to the version.

Default: Not applicable
localestring?

Locale of the entry version.

Default: null
forcebool

Replaces a name the version already has.

Default: false

Returns: ContentstackResponse. The API response with the named version.

Validation

  • Throws InvalidOperationException if the instance has no version number, because SetName names one version. Call .Version(<number>).
  • The SDK does not check name. A null name leaves _version_name out of the body.
  • The SDK does not check locale or the version number. A value that names no locale or version reaches the API and fails there.
  • Throws ContentstackErrorException when the API rejects the request.

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

Behavior

  • Sends one POST request to <ENTRY_OR_ASSET_PATH>/versions/<VERSION_NUMBER>/name, with the body {"entry": {"_version_name": ..., "locale": ..., "force": true}}. On an asset, the body key is asset.
  • Leaves locale out when it is null, and force out when it is false.
  • force set to true replaces a name the version already has. See Set Version Name for Entry and Set Version Name for Asset in the Content Management API (CMA) reference.
  • Returns the raw API response.

Example

Basic usage: name a version of an entry

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>").Version(2).SetName("Launch copy");
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: rename a localized version that already has a name

using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>")
        .Version(2)
        .SetName("Launch copy, approved", locale: "<LOCALE_CODE>", force: true);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Edge case: calling SetName without a version number

using System;
using Contentstack.Management.Core;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    client.Stack("<API_KEY>").Asset("<ASSET_UID>").Version().SetName("Original upload");
}
catch (InvalidOperationException e)
{
    // Thrown before any request because SetName needs a version number
    Console.WriteLine(e.Message);
}

SetNameAsync

SetNameAsync assigns a name to the version whose number you passed to Version(), without blocking the calling thread.

NameTypeDescription
name (required)string

Name to assign to the version.

Default: Not applicable
localestring?

Locale of the entry version.

Default: null
forcebool

Replaces a name the version already has.

Default: false

Returns: Task<ContentstackResponse>. The API response with the named version.

Validation

  • Throws InvalidOperationException if the instance has no version number, because SetNameAsync names one version. The SDK throws it when you call SetNameAsync, before it returns a task.
  • Throws ContentstackErrorException when the API rejects the request. The exception surfaces when you await the task.

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

Behavior

Example

Basic usage: name a version of an asset

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").Asset("<ASSET_UID>").Version(1).SetNameAsync("Original upload");
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    // Thrown when the API rejects the request
    Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}

All parameters: rename a localized entry version

using System;
using System.Threading.Tasks;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").ContentType("<CONTENT_TYPE_UID>").Entry("<ENTRY_UID>")
        .Version(2)
        .SetNameAsync("Launch copy, approved", "<LOCALE_CODE>", true);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}