VariantGroups

View as Markdown

VariantGroups

The VariantGroup class lists the variant groups of a stack, and links content types to a variant group or unlinks them.

When to Use This Class: Use this class before you create entry variants. A content type needs a link to a variant group before its entries can have variants of that group.

Conceptual Role: Acts as the Content Management API (CMA) client for the /variant_groups endpoint. Call stack.VariantGroup() to get an instance.

Returns: VariantGroup. A handle for variant group operations.

Instance State

The UID you pass to stack.VariantGroup() decides which methods you can call on the instance:

  • Call stack.VariantGroup() without a UID to list variant groups with Find or FindAsync.
  • Call stack.VariantGroup("<VARIANT_GROUP_UID>") to work with one group, for example LinkContentTypes or UnlinkContentTypes.

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 The SDK checks for an empty string as if it were no UID, so stack.VariantGroup("") allows Find, and the request path then ends in /variant_groups/. Call stack.VariantGroup() with no argument when you mean the list.

Class-Level Notes

Getting an instance.

  • stack.VariantGroup() throws InvalidOperationException when the client has no authtoken and the stack has no management token, or when the stack has no API key.
  • The Uid property of an instance has no public setter. Call stack.VariantGroup() again to work with another group.

What a variant group does.

  • A variant group holds variants that share the same linked content types. Each variant in the group becomes available on entries of those content types.
  • The CMA reference notes that the variants feature may not be available to every organization. See Variant Groups.
  • Use the EntryVariant class to create the variant content of an entry after you link its content type.

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
Create, rename, or delete a variant groupNoThe CMA has these requests, and this SDK has no method for them.
Create, list, update, or delete the variants of a groupNoThe CMA has these requests, and this SDK has no method for them.
Fetch one variant groupNoCall Find and read the group from the list.

Method Index

List variant groups. Available on stack.VariantGroup() when you pass no UID.

Method NameReturnsDescription
FindThe API response with the variant groups.Lists the variant groups of the stack.
FindAsyncThe API response with the variant groups.Lists the variant groups asynchronously.

Link and unlink content types. Available on stack.VariantGroup("<VARIANT_GROUP_UID>").

Method NameReturnsDescription
LinkContentTypesThe API response with the updated variant group.Links content types to the group.
LinkContentTypesAsyncThe API response with the updated variant group.Links content types asynchronously.
UnlinkContentTypesThe API response with the updated variant group.Unlinks content types from the group.
UnlinkContentTypesAsyncThe API response with the updated variant group.Unlinks content types asynchronously.

Class-Level Snippet

The snippet below lists the variant groups of a stack and links one content type to a group.

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;

ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");

try
{
    ContentstackResponse groups = await stack.VariantGroup().FindAsync();
    Console.WriteLine(groups.OpenJsonObjectResponse().ToJsonString());

    List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };
    await stack.VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypesAsync(contentTypeUids);
}
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 VariantGroup class has its own section below, with its parameters, validation rules, behavior, and examples.

Find

Find lists the variant groups of the stack.

NameTypeDescription
collectionParameterCollection?

Query parameters, for example include_variant_info.

Default: null

Returns: ContentstackResponse. The API response with the variant groups.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws InvalidOperationException if the instance has a UID, because Find lists every group. Call stack.VariantGroup() with no UID.
  • 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 /variant_groups, with the entries of collection as query parameters.
  • The Content Management API (CMA) reference lists the query parameters below for this request. See Get all variant groups.
    • skip and limit: the page of groups to return.
    • include_count, include_variant_info, and include_variant_count: the total, the variants, and the variant count of each group.
    • asc and desc: the sort order, by created_at or name.
    • content_type: only the groups linked to that content type UID.
  • Does not page through the results for you. Without limit and skip, the API applies its own page size.
  • Returns the raw API response.

Example

Basic usage: list the variant groups of a stack

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

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

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup().Find();
    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 groups of one content type with their variants

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("content_type", "<CONTENT_TYPE_UID>");
collection.Add("include_variant_info", true);
collection.Add("include_count", true);
collection.Add("desc", "created_at");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup().Find(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Management token: list the variant groups

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

ContentstackClient client = new ContentstackClient();

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

FindAsync

FindAsync lists the variant groups of the stack, without blocking the calling thread.

NameTypeDescription
collectionParameterCollection?

Query parameters, for example include_variant_info.

Default: null

Returns: Task<ContentstackResponse>. The API response with the variant groups.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws InvalidOperationException if the instance has a UID, because FindAsync lists every group.
  • The SDK throws the exceptions above when you call FindAsync, 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 variant groups of a stack

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>").VariantGroup().FindAsync();
    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: read the first 10 groups with their variant counts

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("limit", 10);
collection.Add("include_variant_count", true);

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").VariantGroup().FindAsync(collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

LinkContentTypes

LinkContentTypes links the content types you list to the variant group whose UID you passed to stack.VariantGroup().

NameTypeDescription
contentTypeUids (required)List<string>

Content type UIDs to link.

Default: Not applicable
collectionParameterCollection?

Query parameters for the request.

Default: null

Returns: ContentstackResponse. The API response with the updated variant group.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws InvalidOperationException if the instance has no UID, because the request path names the group. Call stack.VariantGroup("<VARIANT_GROUP_UID>").
  • Throws ArgumentNullException (parameter contentTypeUids) if contentTypeUids is null or empty, because the request needs at least one content type.
  • The SDK does not check that each UID names a content type. The API rejects a UID that does not.
  • 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 PUT request to /variant_groups/<VARIANT_GROUP_UID>/variants. See Link content types in the Content Management API (CMA) reference.
  • Builds the body from your list:
    • content_types: one object per UID, with status set to linked.
    • uid: the variant group UID.
    • branches: always ["main"], whatever branch the Stack targets.
  • Sends the entries of collection as query parameters.
  • Returns the raw API response.

Example

Basic usage: link a content type to a variant group

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

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

List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypes(contentTypeUids);
    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: link two content types with a query parameter collection

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

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

List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>", "<SECOND_CONTENT_TYPE_UID>" };

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypes(contentTypeUids, collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Edge case: passing an empty list

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;

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

try
{
    client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypes(new List<string>());
}
catch (ArgumentNullException e)
{
    // Thrown before any request because the list holds no content type UID
    Console.WriteLine(e.ParamName);
}

LinkContentTypesAsync

LinkContentTypesAsync links the content types you list to the variant group whose UID you passed to stack.VariantGroup(), without blocking the calling thread.

NameTypeDescription
contentTypeUids (required)List<string>

Content type UIDs to link.

Default: Not applicable
collectionParameterCollection?

Query parameters for the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the updated variant group.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws InvalidOperationException if the instance has no UID, because the request path names the group.
  • Throws ArgumentNullException (parameter contentTypeUids) if contentTypeUids is null or empty.
  • The SDK throws the exceptions above when you call LinkContentTypesAsync, 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: link a content type to a variant group

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

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

List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").LinkContentTypesAsync(contentTypeUids);
    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: link two content types with a management token

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

ContentstackClient client = new ContentstackClient();

List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>", "<SECOND_CONTENT_TYPE_UID>" };

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .VariantGroup("<VARIANT_GROUP_UID>")
        .LinkContentTypesAsync(contentTypeUids, collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

UnlinkContentTypes

UnlinkContentTypes unlinks the content types you list from the variant group whose UID you passed to stack.VariantGroup().

NameTypeDescription
contentTypeUids (required)List<string>

Content type UIDs to unlink.

Default: Not applicable
collectionParameterCollection?

Query parameters for the request.

Default: null

Returns: ContentstackResponse. The API response with the updated variant group.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws InvalidOperationException if the instance has no UID, because the request path names the group. Call stack.VariantGroup("<VARIANT_GROUP_UID>").
  • Throws ArgumentNullException (parameter contentTypeUids) if contentTypeUids is null or empty, because the request needs at least one content type.
  • The SDK does not check that each UID names a content type. The API rejects a UID that does not.
  • 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 PUT request to /variant_groups/<VARIANT_GROUP_UID>/variants. See Unlink content types in the Content Management API (CMA) reference.
  • Builds the body from your list:
    • content_types: one object per UID, with status set to unlinked.
    • uid: the variant group UID.
    • branches: always ["main"], whatever branch the Stack targets.
  • Sends the entries of collection as query parameters.
  • Returns the raw API response.

Example

Basic usage: unlink a content type from a variant group

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

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

List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").UnlinkContentTypes(contentTypeUids);
    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: unlink two content types with a query parameter collection

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

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

List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>", "<SECOND_CONTENT_TYPE_UID>" };

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").UnlinkContentTypes(contentTypeUids, collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}

Edge case: passing an empty list

using System;
using System.Collections.Generic;
using Contentstack.Management.Core;

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

try
{
    client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").UnlinkContentTypes(new List<string>());
}
catch (ArgumentNullException e)
{
    // Thrown before any request because the list holds no content type UID
    Console.WriteLine(e.ParamName);
}

UnlinkContentTypesAsync

UnlinkContentTypesAsync unlinks the content types you list from the variant group whose UID you passed to stack.VariantGroup(), without blocking the calling thread.

NameTypeDescription
contentTypeUids (required)List<string>

Content type UIDs to unlink.

Default: Not applicable
collectionParameterCollection?

Query parameters for the request.

Default: null

Returns: Task<ContentstackResponse>. The API response with the updated variant group.

Validation

  • Throws InvalidOperationException if the client has no authtoken and the stack has no management token.
  • Throws InvalidOperationException if the instance has no UID, because the request path names the group.
  • Throws ArgumentNullException (parameter contentTypeUids) if contentTypeUids is null or empty.
  • The SDK throws the exceptions above when you call UnlinkContentTypesAsync, 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: unlink a content type from a variant group

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

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

List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>" };

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>").VariantGroup("<VARIANT_GROUP_UID>").UnlinkContentTypesAsync(contentTypeUids);
    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: unlink two content types with a management token

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

ContentstackClient client = new ContentstackClient();

List<string> contentTypeUids = new List<string> { "<CONTENT_TYPE_UID>", "<SECOND_CONTENT_TYPE_UID>" };

ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");

try
{
    ContentstackResponse response = await client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
        .VariantGroup("<VARIANT_GROUP_UID>")
        .UnlinkContentTypesAsync(contentTypeUids, collection);
    Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
    Console.WriteLine(e.ErrorMessage);
}