Entry

View as Markdown

Entry

An entry is one piece of content that you create from a content type. Use this class to

  • fetch one published entry by its UID, in a locale, a branch or a variant
  • shape the response with field lists, references, metadata and embedded items
  • read the fields of a loaded entry as raw values, assets, groups or referenced entries

Entry sends one request, through fetch:. Every other method either records a setting for that request or reads the data that a request already loaded.

NameTypeDescription
uid NSString *

Read-only. UID of the entry. Takes the uid of each loaded entry.

deleted BOOL

Read-only. YES after the entry loads a deleted_at value. The Swift name is isDeleted.

tags NSArray<NSString *> *

Read-only. Tags of the loaded entry.

contentTypeName NSString *

Read-only. UID of the content type that the entry belongs to.

title NSString *

Read-only. title field of the loaded entry.

url NSString *

Read-only. url field of the loaded entry.

locale NSString *

Locale that the next fetch: requests. After a fetch, the locale of the loaded entry. Known issue: the property does not retain its string. See the Class-Level Notes above.

createdAt NSDate *

Read-only. Creation date of the loaded entry. Known issue: reading it unset crashes a Swift app.

createdBy NSString *

Read-only. UID of the user who created the entry.

updatedAt NSDate *

Read-only. Last update date of the loaded entry. Known issue: reading it unset crashes a Swift app.

updatedBy NSString *

Read-only. UID of the user who last updated the entry.

deletedAt NSDate *

Read-only. Deletion date, set only when the loaded data contains deleted_at. Known issue: reading it unset crashes a Swift app.

deletedBy NSString *

Read-only. UID of the user who deleted the entry, when the loaded data contains deleted_by.

cachePolicy CachePolicy

Caching strategy for fetch:. Known issue: CACHE_ONLY, CACHE_ELSE_NETWORK and CACHE_THEN_NETWORK never read the cache and always send a network request. Use NETWORK_ELSE_CACHE for an offline fallback. See CachePolicy.

properties NSDictionary<NSString *, id> *

Read-only. Every field of the loaded entry, as raw JSON values.

HTMLArrayForMarkdownKey:

HTMLArrayForMarkdownKey: converts each value of a multiple Markdown field of the loaded entry to an HTML string.

NameTypeDescription
key (required)NSString *

UID of the multiple Markdown field to convert.

Default: Not applicable

Returns: NSArray. The HTML for each Markdown value under the key, or nil.

Validation

  • There is no client-side validation.
  • HTMLArrayForMarkdownKey: returns nil in each of these cases:
    • The entry holds no value under the key.
    • The value is not an array, for example the string of a single Markdown field.
    • The conversion of any element fails.

Behavior

  • Client-side only. HTMLArrayForMarkdownKey: converts the values that the entry already holds, and makes no request.
  • The result keeps the order of the field value, with one HTML string for each Markdown string.
  • The SDK converts with GitHub Flavored Markdown extensions, the same as the HTMLStringForMarkdownKey: method.
  • In Swift, the method is htmlArray(forMarkdownKey:) and returns [Any]?.

Example

Render a multiple Markdown field as HTML (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (NSString *html in [entry HTMLArrayForMarkdownKey:@"faq_answers"]) {
        NSLog(@"%@", html);
    }
}];

Render a multiple Markdown field as HTML (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for case let html as String in entry.htmlArray(forMarkdownKey: "faq_answers") ?? [] {
        print(html)
    }
}

HTMLStringForMarkdownKey:

HTMLStringForMarkdownKey: converts the value of a Markdown field of the loaded entry to an HTML string.

NameTypeDescription
key (required)NSString *

UID of the Markdown field to convert.

Default: Not applicable

Returns: NSString. The HTML for the Markdown value under the key, or nil.

Validation

  • There is no client-side validation.
  • HTMLStringForMarkdownKey: returns nil in each of these cases:
    • The entry holds no value under the key.
    • The value is not a string, for example the array of a multiple Markdown field.
    • The value is an empty string.
    • The conversion fails.

Behavior

  • Client-side only. HTMLStringForMarkdownKey: converts the value that the entry already holds, and makes no request.
  • The SDK converts with GitHub Flavored Markdown extensions, so tables, fenced code blocks and strikethrough produce HTML.
  • A Markdown field marked as multiple holds an array. Use the HTMLArrayForMarkdownKey: method for it.
  • In Swift, the method is htmlString(forMarkdownKey:) and returns String?.

Example

Render a Markdown field as HTML (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSString *html = [entry HTMLStringForMarkdownKey:@"description"];
    NSLog(@"%@", html ?: @"No Markdown under description");
}];

Render a Markdown field as HTML (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.htmlString(forMarkdownKey: "description") ?? "No Markdown under description")
}

addHeadersWithDictionary:

addHeadersWithDictionary: adds several HTTP headers to the requests of this entry in one call.

NameTypeDescription
headers (required)NSDictionary<NSString *, NSString *> *

Header names mapped to their values.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, passing nil adds no header and raises no error.

Behavior

  • Client-side only. addHeadersWithDictionary: copies each pair into the headers of this entry and makes no request.
  • A name that the entry already holds takes the new value. Headers with other names stay.
  • The headers follow the same rules as on the setHeader:forKey: method.
    • An entry header replaces a stack or content type header of the same name.
    • The SDK writes X-User-Agent, User-Agent and a configured branch after yours.

Example

Add a branch and a variant header together (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry addHeadersWithDictionary:@{@"branch": @"BRANCH_UID", @"x-cs-variant-uid": @"VARIANT_UID"}];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Add a branch and a variant header together (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.addHeaders(with: ["branch": "BRANCH_UID", "x-cs-variant-uid": "VARIANT_UID"])
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

addParamKey:andValue:

addParamKey:andValue: adds one query parameter to the next fetch of this entry.

NameTypeDescription
key (required)NSString *

Name of the query parameter.

Default: Not applicable
value (required)NSString *

Value of the query parameter.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation. addParamKey:andValue: does not check the parameter name against the API.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, a nil key adds nothing. A nil value with a non-nil key raises NSInvalidArgumentException, because the entry keeps its parameters in a dictionary that rejects nil. Swift does not accept nil for either argument.

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

Behavior

  • Client-side only. addParamKey:andValue: records the pair in the request parameters of this entry and makes no request.
  • A key that the entry already holds takes the new value. This includes parameters that other methods write, such as locale and include_fallback.
  • fetch: writes the stack environment to environment on every call, so a value you add under environment does not reach the request.
  • Use it for a Delivery API parameter that has no method on Entry, for example include_all. All Query Parameters lists the parameters that each request accepts.

Example

Include every referenced entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry addParamKey:@"include_all" andValue:@"true"];
[entry addParamKey:@"include_all_depth" andValue:@"2"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Include every referenced entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.addParamKey("include_all", andValue: "true")
entry.addParamKey("include_all_depth", andValue: "2")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

assetForKey:

assetForKey: returns the asset in a single file field of the loaded entry as an Asset object.

NameTypeDescription
key (required)NSString *

UID of the file field to read.

Default: Not applicable

Returns: Asset. The asset stored under the key, or nil.

Validation

  • There is no client-side validation.
  • A key that the entry does not hold, or a value that is not a JSON object, returns nil.

Known issue In Swift, asset(forKey:) returns a non-optional Asset even when the SDK finds no asset, and using that value can crash the app. Check that entry.object(forKey:) returns a [String: Any] for the key before you call asset(forKey:).

Behavior

  • Client-side only. assetForKey: builds an Asset from the field value that the entry already holds, and makes no request.
  • The Asset exposes the asset details from the entry response, such as uid, fileName, url and fileType. See the Asset class.
  • A file field that allows multiple files holds an array. Use the assetsForKey: method for it, because assetForKey: returns nil for an array.
  • On an entry from a taxonomy query, assetForKey: returns nil. See the Known issue on the Entry class page.

Example

Read the banner image of an entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    Asset *banner = [entry assetForKey:@"banner"];
    if (banner) {
        NSLog(@"%@ %@", banner.fileName, banner.url);
    }
}];

Read the banner image of an entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    // Check the raw value first, because asset(forKey:) is non-optional in Swift.
    if entry.object(forKey: "banner") is [String: Any] {
        let banner = entry.asset(forKey: "banner")
        print(banner.fileName, banner.url)
    }
}

assetsForKey:

assetsForKey: returns the assets in a multiple file field of the loaded entry as Asset objects.

NameTypeDescription
key (required)NSString *

UID of the multiple file field to read.

Default: Not applicable

Returns: NSArray. The assets stored under the key, or an empty array.

Validation

  • There is no client-side validation.
  • A key that the entry does not hold, or a value that is not an array, returns an empty array.

Behavior

  • Client-side only. assetsForKey: builds one Asset for each element of the array that the entry already holds, and makes no request.
  • The array keeps the order of the field value.
  • Each Asset exposes the asset details from the entry response, such as uid, fileName, url and fileType. See the Asset class.
  • A file field that allows one file holds a single object. Use the assetForKey: method for it, because assetsForKey: returns an empty array for an object.
  • On an entry from a taxonomy query, assetsForKey: returns an empty array. See the Known issue on the Entry class page.

Example

List the gallery images of an entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (Asset *image in [entry assetsForKey:@"gallery"]) {
        NSLog(@"%@ %@", image.fileName, image.url);
    }
}];

List the gallery images of an entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for case let image as Asset in entry.assets(forKey: "gallery") {
        print(image.fileName, image.url)
    }
}

cancelRequest

cancelRequest stops the running fetch: request of this entry.

Returns: void. Nothing.

Validation

  • There is no client-side validation.
  • When no request of this entry is running, cancelRequest does nothing.

Behavior

  • Client-side only. cancelRequest cancels the entry's request only while it runs, and leaves a finished request alone.
  • The completion block of the cancelled fetch: still runs. It receives an NSError in the NSURLErrorDomain domain with code NSURLErrorCancelled. Check for that code to tell a cancellation from a failed request.
  • When the entry's cachePolicy is NETWORK_ELSE_CACHE, a cancelled request reads the cache instead. The completion block then receives the cached entry, or an NSError in the CacheError domain when the cache holds no copy.
  • fetch: calls cancelRequest before it sends a request, so a second fetch: on the same entry cancels the first.
  • cancelRequest affects only this entry. Requests of other entries and queries keep running.

Limitations

  • Does not stop a retry that the SDK starts after a 408 or 429 response. The retry runs as a new request that the entry does not track.

Example

Cancel a running fetch (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        if ([error.domain isEqualToString:NSURLErrorDomain] && error.code == NSURLErrorCancelled) {
            NSLog(@"Fetch cancelled");
            return;
        }
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];
[entry cancelRequest];

Cancel a running fetch (Swift)

import Contentstack
import Foundation

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        if error.domain == NSURLErrorDomain && error.code == NSURLErrorCancelled {
            print("Fetch cancelled")
            return
        }
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}
entry.cancelRequest()

configureWithDictionary:

configureWithDictionary: loads entry fields from a dictionary that you supply, without a request.

NameTypeDescription
dictionary (required)NSDictionary<NSString *, id> *

Entry JSON to load, with field UIDs as keys.

Default: Not applicable

Returns: void. Nothing. The entry holds the fields from the dictionary.

Validation

  • There is no client-side validation. configureWithDictionary: does not check the dictionary against the content type.
  • In Objective-C, passing nil clears every field of the entry.

Behavior

  • Client-side only. configureWithDictionary: makes no request. fetch: calls it with the entry object of each response.
  • The dictionary replaces the fields of the entry. Keys in the dictionary overwrite the old values, and keys missing from it disappear from properties and objectForKey:.
  • The typed properties take a value only when the dictionary holds their key:
    • uid, title, url, tags, locale, created_by, updated_by and deleted_by copy the value.
    • created_at, updated_at and deleted_at parse an ISO 8601 date.
    • A deleted_at key also sets deleted to YES.
  • A property whose key is missing from the dictionary keeps its earlier value. For example, title still returns the old title after you load a dictionary without title.
  • A uid key changes the UID that the next fetch: requests, and a locale key changes the locale that it requests.

Example

Load an entry from saved JSON (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
NSDictionary *saved = @{@"uid": @"ENTRY_UID", @"title": @"Spring launch", @"url": @"/spring-launch", @"locale": @"en-us"};
[entry configureWithDictionary:saved];
NSLog(@"%@ at %@", entry.title, entry.url);

Load an entry from saved JSON (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
let saved: [String: Any] = ["uid": "ENTRY_UID", "title": "Spring launch", "url": "/spring-launch", "locale": "en-us"]
entry.configure(with: saved)
print(entry.title, entry.url)

entriesForKey:withContentType:

entriesForKey:withContentType: returns the entries in a reference field of the loaded entry as Entry objects.

NameTypeDescription
referenceKey (required)NSString *

UID of the reference field to read.

Default: Not applicable
contentTypeName (required)NSString *

Content type UID to give each returned entry.

Default: Not applicable

Returns: NSArray. The referenced entries stored under the key, or nil.

Validation

  • There is no client-side validation. entriesForKey:withContentType: does not check contentTypeName against the referenced entries.
  • A key that the entry does not hold, or a value that is not an array, returns nil in Objective-C and an empty array in Swift.

Behavior

  • Client-side only. entriesForKey:withContentType: builds one Entry for each element of the reference field, and makes no request.
  • The content of each Entry depends on whether the fetch that loaded the parent resolved the field, in the two cases below:
    • When the fetch resolved the field with the includeRefFieldWithKey: method, each Entry holds the full referenced entry, as Include Reference describes.
    • Otherwise each Entry holds only uid and _content_type_uid. Call fetch: on it to load its fields.
  • Every returned Entry belongs to the content type that you pass, even when the field references entries of several content types. For such a field, call the includeReferenceContentTypeUid method before the fetch. Each referenced entry then includes its real content type UID under _content_type_uid, which you read with objectForKey:.
  • In Swift, the method is entries(forKey:withContentType:) and returns [Any]. Cast each element to Entry.

Example

Read resolved references (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeRefFieldWithKey:@[@"related_articles"]];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (Entry *article in [entry entriesForKey:@"related_articles" withContentType:@"article"]) {
        NSLog(@"%@ %@", article.uid, article.title);
    }
}];

Read resolved references (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeRefField(withKey: ["related_articles"])
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for case let article as Entry in entry.entries(forKey: "related_articles", withContentType: "article") {
        print(article.uid, article.title)
    }
}

Fetch a reference that the parent did not resolve (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) { return; }
    Entry *article = [entry entriesForKey:@"related_articles" withContentType:@"article"].firstObject;
    // The entry holds only its UID, so fetch it to load its fields.
    [article fetch:^(ResponseType type, NSError *error) {
        if (error) { return; }
        NSLog(@"%@", article.title);
    }];
}];

Fetch a reference that the parent did not resolve (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    guard error == nil else { return }
    guard let article = entry.entries(forKey: "related_articles", withContentType: "article").first as? Entry else { return }
    // The entry holds only its UID, so fetch it to load its fields.
    article.fetch { (type, error) in
        guard error == nil else { return }
        print(article.title)
    }
}

fetch:

fetch: retrieves one published entry by its UID and loads its fields into the entry object.

NameTypeDescription
callback (required)void (^)(ResponseType, NSError *)

Receives the response source and an error, nil on success.

Default: Not applicable

Returns: void. Nothing. The entry holds the fetched fields when the completion block runs.

Validation

  • There is no client-side validation. fetch: places the entry UID in the request path as given, including an empty string.
  • When the API rejects the request, the completion block receives an NSError whose code is the HTTP status and whose userInfo holds error_message, error_code and errors.

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

Behavior

  • One call sends one Get a single entry request (GET /content_types/{content_type_uid}/entries/{entry_uid}), with every parameter and header that the entry holds.
  • fetch: adds the stack's environment as the environment query parameter on every call.
  • The completion block carries no entry data. On success, fetch: loads the entry object of the response into the entry.
  • Read the loaded fields from the typed properties, from properties, or with field readers such as objectForKey:.
  • fetch: keeps only the entry object of the response. A key outside it does not reach your code.
  • When a successful response holds no entry key, fetch: clears the entry's fields and still passes a nil error.
  • On failure, the entry keeps the fields it held before the call.
  • The loaded entry's locale value replaces the locale property, and the next fetch: requests that locale. After a fetch that fell back to another locale through includeFallback, the next fetch asks for the fallback locale.
  • A second fetch: on the same entry cancels the first one if it is still running. The first call's completion block then receives an NSError with code NSURLErrorCancelled. See the cancelRequest method.
  • The cachePolicy property of the entry decides whether fetch: reads or writes the cache. The default, NETWORK_ONLY, always sends a request and never reads the cache. See the CachePolicy values.
  • In Swift, fetch(_:) has only the completion-block form. There is no async variant.

Example

Fetch an entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Fetch an entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

Fetch a localized entry with fallback (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
entry.locale = @"fr-fr";
[entry includeFallback];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) { return; }
    // The locale property now holds the locale the API returned.
    NSLog(@"%@ (%@)", entry.title, entry.locale);
}];

Fetch a localized entry with fallback (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.locale = "fr-fr"
entry.includeFallback()
entry.fetch { (type, error) in
    guard error == nil else { return }
    // The locale property now holds the locale the API returned.
    print(entry.title, entry.locale)
}

groupForKey:

groupForKey: returns the value of a single Group field of the loaded entry as a Group object.

NameTypeDescription
key (required)NSString *

UID of the Group field to read.

Default: Not applicable

Returns: Group. The group stored under the key, or nil.

Validation

  • There is no client-side validation.
  • A key that the entry does not hold, or a value that is not a JSON object, returns nil.

Behavior

  • Client-side only. groupForKey: copies the field value that the entry already holds into a new Group, and makes no request.
  • The Group keeps the values from the moment of the call. A later fetch: of the entry does not update it, so call groupForKey: again after each fetch.
  • Read the subfields with the methods of the Group class, such as objectForKey:.
  • A Group field marked as multiple holds an array. Use the groupsForKey: method for it, because groupForKey: returns nil for an array.
  • In Swift, the method is group(forKey:) and returns Group?.

Example

Read the subfields of a Group field (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    Group *seo = [entry groupForKey:@"seo"];
    if (seo) {
        NSLog(@"%@", [seo objectForKey:@"meta_title"]);
    }
}];

Read the subfields of a Group field (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    if let seo = entry.group(forKey: "seo") {
        print(seo.object(forKey: "meta_title") ?? "")
    }
}

groupsForKey:

groupsForKey: returns the values of a multiple Group field of the loaded entry as Group objects.

NameTypeDescription
key (required)NSString *

UID of the multiple Group field to read.

Default: Not applicable

Returns: NSArray. The groups stored under the key, or nil.

Validation

  • There is no client-side validation.
  • A key that the entry does not hold, or a value that is not an array, returns nil in Objective-C and an empty array in Swift.

Behavior

  • Client-side only. groupsForKey: copies each element of the array that the entry already holds into a new Group, and makes no request.
  • The array keeps the order of the field value.
  • Each Group keeps the values from the moment of the call. A later fetch: of the entry does not update them.
  • Read the subfields with the methods of the Group class.
  • A Group field that allows one value holds a single object. Use the groupForKey: method for it.
  • In Swift, the method is groups(forKey:) and returns [Any]. Cast each element to Group.

Example

List the addresses in a multiple Group field (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (Group *address in [entry groupsForKey:@"addresses"]) {
        NSLog(@"%@, %@", [address objectForKey:@"street"], [address objectForKey:@"city"]);
    }
}];

List the addresses in a multiple Group field (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for case let address as Group in entry.groups(forKey: "addresses") {
        print(address.object(forKey: "street") ?? "", address.object(forKey: "city") ?? "")
    }
}

hasKey:

hasKey: checks whether the entry holds a value under a key.

NameTypeDescription
key (required)NSString *

Field UID or parameter name to check.

Default: Not applicable

Returns: BOOL. YES when the entry holds a field or request parameter under the key, otherwise NO.

Validation

  • There is no client-side validation.
  • In Objective-C, a nil key returns NO.

Behavior

  • Client-side only. hasKey: makes no request.
  • It checks two places and returns YES when either holds the key:
    • The fields of the loaded entry.
    • The request parameters of the entry, such as locale, include_fallback, or environment after the first fetch.
  • A field whose value is JSON null counts as present.
  • To test only the loaded fields, check that objectForKey: returns a value.

Example

Check a field before you read it (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    if ([entry hasKey:@"summary"]) {
        NSLog(@"%@", [entry objectForKey:@"summary"]);
    }
}];

Check a field before you read it (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    if entry.hasKey("summary") {
        print(entry.object(forKey: "summary") ?? "")
    }
}

Edge case: a request parameter also counts (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeFallback];
// YES before any fetch, because include_fallback is a request parameter of the entry.
NSLog(@"%d", [entry hasKey:@"include_fallback"]);

Edge case: a request parameter also counts (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeFallback()
// true before any fetch, because include_fallback is a request parameter of the entry.
print(entry.hasKey("include_fallback"))

includeAllFieldsExcept:

includeAllFieldsExcept: leaves the top-level fields you name out of the next fetch.

NameTypeDescription
fieldUIDs (required)NSArray *

UIDs of the top-level fields to leave out.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation. includeAllFieldsExcept: does not check that the fields exist.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, passing nil raises NSInvalidArgumentException, because the entry keeps its parameters in a dictionary that rejects nil. Swift does not accept nil here.

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

Behavior

  • Client-side only. includeAllFieldsExcept: writes the list as except[BASE][] to the request parameters of this entry and makes no request.
  • fetch: sends the list in the shape that the Exclude Operator describes. The API returns every field of the entry except the named ones.
  • Name a field inside a Group field with a dot path, such as seo.meta_title, as Exclude Operator Within Group describes.
  • A second call replaces the list from the first. Pass every field in one call.
  • The list shares the except parameter with the includeRefFieldWithKey:excludingRefValuesWithKeys: method, and the two calls keep their own keys.
  • Use the includeOnlyFields: method to name the fields to keep instead.

Example

Leave out a large body field (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeAllFieldsExcept:@[@"body"]];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@ has body: %d", entry.title, [entry objectForKey:@"body"] != nil);
}];

Leave out a large body field (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeAllFieldsExcept(["body"])
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title, "has body:", entry.object(forKey: "body") != nil)
}

includeBranch

includeBranch asks the API to name the branch that holds the entry.

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.

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

Behavior

  • Client-side only. includeBranch adds include_branch=true to the request parameters of this entry and makes no request.
  • fetch: sends the parameter with the Get a single entry request. The API reference describes _branch as a top-level key of the response.
  • fetch: loads only the entry object of the response into the entry. A top-level key outside that object does not reach your code.
  • includeBranch does not choose a branch. Send the branch header with the setHeader:forKey: method, or set a branch in the stack configuration.
  • The parameter stays on the entry for every later fetch. No method removes it.

Example

Fetch an entry from a branch with branch details (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry setHeader:@"BRANCH_UID" forKey:@"branch"];
[entry includeBranch];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@ %@", entry.title, [entry objectForKey:@"_branch"]);
}];

Fetch an entry from a branch with branch details (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.setHeader("BRANCH_UID", forKey: "branch")
entry.includeBranch()
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title, entry.object(forKey: "_branch") ?? "no _branch key")
}

includeContentType

includeContentType asks the API to return the content type of the entry, with Global field schemas, on the next fetch.

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.

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

Behavior

  • Client-side only. includeContentType adds two parameters to the request parameters of this entry and makes no request:
    • include_content_type=true
    • include_global_field_schema=true, which the Get all content types request describes as adding the schema of each Global field.
  • fetch: loads only the entry object of the response into the entry. A top-level key outside that object does not reach your code.
  • The parameters stay on the entry for every later fetch. No method removes them.

Limitations

  • Does not give your code a typed content type object. To read a content type schema, use the fetch:completion: method of ContentType.

Example

Request the content type with the entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeContentType];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Request the content type with the entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeContentType()
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

includeEmbeddedItems

includeEmbeddedItems asks the API to return the entries and assets embedded in the Rich Text Editor fields of the entry.

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.

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

Behavior

  • Client-side only. includeEmbeddedItems adds include_embedded_items[]=BASE to the request parameters of this entry and makes no request.
  • fetch: sends the parameter in the shape that Get information on embedded RTE objects describes. The API returns the first level of embedded entries and assets under the _embedded_items key.
  • The SDK has no typed accessor for embedded items. Read the _embedded_items value with objectForKey:.
  • The parameter stays on the entry for every later fetch. No method removes it.

Limitations

  • Does not request embedded items nested inside other embedded items. The SDK always sends BASE, never RECURSIVE.

Example

Fetch an entry with its embedded items (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeEmbeddedItems];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSDictionary *embedded = [entry objectForKey:@"_embedded_items"];
    NSLog(@"Embedded items by field: %@", embedded.allKeys);
}];

Fetch an entry with its embedded items (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeEmbeddedItems()
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    let embedded = entry.object(forKey: "_embedded_items") as? [String: Any] ?? [:]
    print("Embedded items by field: \(Array(embedded.keys))")
}

includeFallback

includeFallback returns the entry from the fallback locale when it has no published version in the requested locale.

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.

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

Behavior

  • Client-side only. includeFallback adds include_fallback=true to the request parameters of this entry and makes no request.
  • fetch: sends the parameter with the Get a single entry request. When the requested locale holds no published content, the API returns the published content of the fallback locale.
  • Set the requested locale with the locale property of the entry before the fetch.
  • After the fetch, the locale property holds the locale that the API returned, and the next fetch: requests that locale. Set locale again before a later fetch to ask for the original locale.
  • The parameter stays on the entry for every later fetch. No method removes it.

Example

Fetch French content with an English fallback (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
entry.locale = @"fr-fr";
[entry includeFallback];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@ returned in %@", entry.title, entry.locale);
}];

Fetch French content with an English fallback (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.locale = "fr-fr"
entry.includeFallback()
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(entry.title) returned in \(entry.locale)")
}

includeMetadata

includeMetadata adds the metadata of the entry to the next fetch.

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.

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

Behavior

  • Client-side only. includeMetadata adds include_metadata=true to the request parameters of this entry and makes no request.
  • fetch: sends the parameter with the Get a single entry request. The API returns the entry metadata under the _metadata key, with one list for each extension UID.
  • The SDK has no typed property for metadata. Read the _metadata value with objectForKey:.
  • The parameter stays on the entry for every later fetch. No method removes it.

Example

Fetch an entry with its metadata (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeMetadata];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSDictionary *metadata = [entry objectForKey:@"_metadata"];
    NSLog(@"%@", metadata[@"extensions"]);
}];

Fetch an entry with its metadata (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeMetadata()
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    if let metadata = entry.object(forKey: "_metadata") as? [String: Any] {
        print(metadata["extensions"] ?? "")
    }
}

includeOnlyFields:

includeOnlyFields: limits the next fetch to the top-level fields you name.

NameTypeDescription
fieldUIDs (required)NSArray *

UIDs of the top-level fields to return.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation. includeOnlyFields: does not check that the fields exist.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, passing nil raises NSInvalidArgumentException, because the entry keeps its parameters in a dictionary that rejects nil. Swift does not accept nil here.

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

Behavior

  • Client-side only. includeOnlyFields: writes the list as only[BASE][] to the request parameters of this entry and makes no request.
  • fetch: sends the list in the shape that the Only Operator describes. The API returns only the named fields of the entry.
  • Name a field inside a Group field with a dot path, such as seo.meta_title, as Only Operator Within Group describes.
  • A second call replaces the list from the first. Pass every field in one call.
  • The list shares the only parameter with the includeRefFieldWithKey:andOnlyRefValuesWithKeys: method, and the two calls keep their own keys.
  • Use the includeAllFieldsExcept: method to name the fields to leave out instead.

Example

Return only the title and URL (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeOnlyFields:@[@"title", @"url"]];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@ %@", entry.title, entry.url);
}];

Return only the title and URL (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeOnlyFields(["title", "url"])
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title, entry.url)
}

includeRefFieldWithKey:

includeRefFieldWithKey: asks the API to return the full content of the referenced entries in the reference fields you name.

NameTypeDescription
key (required)NSArray *

UIDs or dot paths of the reference fields to resolve.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation. includeRefFieldWithKey: does not check that the fields exist or hold references.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, passing nil adds no field and raises no error.

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

Behavior

  • Client-side only. includeRefFieldWithKey: adds each value to the include[] request parameter of this entry and makes no request.
  • fetch: sends the list in the shape that Include Reference describes. Without it, a reference field holds only the UID and content type UID of each referenced entry.
  • Name a nested reference field with a dot path, in the two cases below:
  • Each call adds to the list from earlier calls. No method removes a field from it.
  • Read the resolved entries as Entry objects with the entriesForKey:withContentType: method, or as raw dictionaries with objectForKey:.

Example

Resolve a reference field (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeRefFieldWithKey:@[@"author"]];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (Entry *author in [entry entriesForKey:@"author" withContentType:@"author"]) {
        NSLog(@"%@", author.title);
    }
}];

Resolve a reference field (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeRefField(withKey: ["author"])
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for case let author as Entry in entry.entries(forKey: "author", withContentType: "author") {
        print(author.title)
    }
}

Resolve a reference inside a Group field (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
// "seo" is a Group field that holds the "related_pages" reference field.
[entry includeRefFieldWithKey:@[@"author", @"seo.related_pages"]];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) { return; }
    Group *seo = [entry groupForKey:@"seo"];
    NSLog(@"%lu related pages", (unsigned long)[seo entriesForKey:@"related_pages" withContentType:@"page"].count);
}];

Resolve a reference inside a Group field (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
// "seo" is a Group field that holds the "related_pages" reference field.
entry.includeRefField(withKey: ["author", "seo.related_pages"])
entry.fetch { (type, error) in
    guard error == nil else { return }
    if let seo = entry.group(forKey: "seo") {
        print(seo.entries(forKey: "related_pages", withContentType: "page").count, "related pages")
    }
}

includeRefFieldWithKey:andOnlyRefValuesWithKeys:

includeRefFieldWithKey:andOnlyRefValuesWithKeys: resolves one reference field and returns only the fields you name from each referenced entry.

NameTypeDescription
key (required)NSString *

UID of the reference field to resolve.

Default: Not applicable
values (required)NSArray *

Fields to return from each referenced entry.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, passing nil for key raises NSInvalidArgumentException, because the SDK places the key in an array that rejects nil. Passing nil for values resolves the reference with no field list. Swift does not accept nil for either argument.

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

Behavior

  • Client-side only. includeRefFieldWithKey:andOnlyRefValuesWithKeys: makes no request. It records two parameters on this entry:
    • It adds key to the include[] list, the same way the includeRefFieldWithKey: method does.
    • It writes values as only[key][].
  • fetch: sends only[key][] in the shape that the Only Operator describes for a reference field. The API returns only the named fields of each referenced entry.
  • A second call with the same key replaces its field list. Calls with other keys add their own lists.
  • The only parameter also holds the list from the includeOnlyFields: method, under the BASE key.
  • Read the referenced entries with the entriesForKey:withContentType: method.

Example

Return only the author name (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeRefFieldWithKey:@"author" andOnlyRefValuesWithKeys:@[@"title", @"email"]];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (Entry *author in [entry entriesForKey:@"author" withContentType:@"author"]) {
        NSLog(@"%@ %@", author.title, [author objectForKey:@"email"]);
    }
}];

Return only the author name (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeRefField(withKey: "author", andOnlyRefValuesWithKeys: ["title", "email"])
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for case let author as Entry in entry.entries(forKey: "author", withContentType: "author") {
        print(author.title, author.object(forKey: "email") ?? "")
    }
}

includeRefFieldWithKey:excludingRefValuesWithKeys:

includeRefFieldWithKey:excludingRefValuesWithKeys: resolves one reference field and leaves the fields you name out of each referenced entry.

NameTypeDescription
key (required)NSString *

UID of the reference field to resolve.

Default: Not applicable
values (required)NSArray *

Fields to leave out of each referenced entry.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, passing nil for key raises NSInvalidArgumentException, because the SDK places the key in an array that rejects nil. Passing nil for values resolves the reference with no field list. Swift does not accept nil for either argument.

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

Behavior

  • Client-side only. includeRefFieldWithKey:excludingRefValuesWithKeys: makes no request. It records two parameters on this entry:
    • It adds key to the include[] list, the same way the includeRefFieldWithKey: method does.
    • It writes values as except[key][].
  • fetch: sends except[key][] in the shape that the Exclude Operator describes for a reference field. The API returns every field of each referenced entry except the named ones.
  • A second call with the same key replaces its field list. Calls with other keys add their own lists.
  • The except parameter also holds the list from the includeAllFieldsExcept: method, under the BASE key.
  • Read the referenced entries with the entriesForKey:withContentType: method.

Example

Leave the author biography out (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeRefFieldWithKey:@"author" excludingRefValuesWithKeys:@[@"biography"]];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (Entry *author in [entry entriesForKey:@"author" withContentType:@"author"]) {
        NSLog(@"%@", author.title);
    }
}];

Leave the author biography out (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeRefField(withKey: "author", excludingRefValuesWithKeys: ["biography"])
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for case let author as Entry in entry.entries(forKey: "author", withContentType: "author") {
        print(author.title)
    }
}

includeReferenceContentTypeUid

includeReferenceContentTypeUid asks the API to add the content type UID to each referenced entry in the response.

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.

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

Behavior

  • Client-side only. includeReferenceContentTypeUid adds include_reference_content_type_uid=true to the request parameters of this entry and makes no request.
  • Each referenced entry then carries its content type UID under the _content_type_uid key. Read it with objectForKey: on the referenced entry.
  • Combine it with the includeRefFieldWithKey: method when a reference field can point to more than one content type.
  • entriesForKey:withContentType: gives every returned entry the one content type you pass. _content_type_uid names the real one.
  • The parameter stays on the entry for every later fetch. No method removes it.

Example

Read the content type of each referenced entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeRefFieldWithKey:@[@"related_articles"]];
[entry includeReferenceContentTypeUid];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (NSDictionary *reference in [entry objectForKey:@"related_articles"]) {
        NSLog(@"%@ is a %@", reference[@"uid"], reference[@"_content_type_uid"]);
    }
}];

Read the content type of each referenced entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeRefField(withKey: ["related_articles"])
entry.includeReferenceContentTypeUid()
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for reference in entry.object(forKey: "related_articles") as? [[String: Any]] ?? [] {
        print(reference["uid"] ?? "", reference["_content_type_uid"] ?? "")
    }
}

includeSchema

includeSchema asks the API to return the content type schema, with Global field schemas, on the next fetch.

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.

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

Behavior

  • Client-side only. includeSchema adds two parameters to the request parameters of this entry and makes no request:
    • include_schema=true
    • include_global_field_schema=true, which the Get all content types request describes as adding the schema of each Global field.
  • fetch: loads only the entry object of the response into the entry. A top-level key outside that object does not reach your code.
  • The parameters stay on the entry for every later fetch. No method removes them.
  • Use the includeContentType method to request the content type in the include_content_type form.

Limitations

  • Does not give your code a typed schema object. To read a content type schema, use the fetch:completion: method of ContentType.

Example

Request the schema with the entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry includeSchema];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Request the schema with the entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.includeSchema()
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

objectForKey:

objectForKey: returns the raw value of one field of the loaded entry.

NameTypeDescription
key (required)NSString *

UID of the field to read.

Default: Not applicable

Returns: id. The value stored under the key, or nil.

Validation

  • There is no client-side validation.
  • A key that the entry does not hold returns nil. In Objective-C, a nil key also returns nil.

Behavior

  • Client-side only. objectForKey: reads the fields that fetch:, a query, or configureWithDictionary: loaded, and makes no request.
  • The value keeps the type that the JSON response gave it:
    • Text fields return NSString.
    • Number and Boolean fields return NSNumber.
    • Multiple fields, reference fields and Modular Blocks return NSArray.
    • Group fields, file fields and other objects return NSDictionary.
    • A JSON null returns NSNull.
  • Subscript syntax calls objectForKey:. In Objective-C, entry[@"title"] returns the same value as [entry objectForKey:@"title"]. In Swift, the subscript takes an NSCopying key, so write entry["title" as NSString], or call entry.object(forKey: "title").
  • A subscript key that is not a string returns nil.
  • Before the entry loads, every key returns nil.
  • Use the typed readers for fields that the SDK can wrap: assetForKey:, groupForKey:, entriesForKey:withContentType: and HTMLStringForMarkdownKey:.

Example

Read a field after a fetch (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSString *summary = [entry objectForKey:@"summary"];
    NSNumber *price = entry[@"price"];
    NSLog(@"%@ costs %@", summary, price);
}];

Read a field after a fetch (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    let summary = entry.object(forKey: "summary") as? String ?? ""
    let price = entry["price" as NSString] as? NSNumber
    print(summary, price ?? 0)
}

removeHeaderForKey:

removeHeaderForKey: removes one HTTP header from the requests of this entry.

NameTypeDescription
headerKey (required)NSString *

Name of the header to remove.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • A name that the entry does not hold, or nil in Objective-C, changes nothing and raises no error.

Behavior

  • Client-side only. removeHeaderForKey: deletes the header from this entry and makes no request.
  • It removes only headers that the entry holds, including the x-cs-variant-uid header that variantUid: and variantUids: write.
  • A header of the same name on the stack or the content type stays, and fetch: still sends it.

Example

Remove a header before the next fetch (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry setHeader:@"BRANCH_UID" forKey:@"branch"];
[entry removeHeaderForKey:@"branch"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Remove a header before the next fetch (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.setHeader("BRANCH_UID", forKey: "branch")
entry.removeHeader(forKey: "branch")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

setHeader:forKey:

setHeader:forKey: adds one HTTP header to the requests of this entry.

NameTypeDescription
headerValue (required)NSString *

Value of the header.

Default: Not applicable
headerKey (required)NSString *

Name of the header.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, passing nil for either argument raises NSInvalidArgumentException, because the entry keeps its headers in a dictionary that rejects nil. Swift does not accept nil here.

Behavior

  • Client-side only. setHeader:forKey: records the header on this entry and makes no request.
  • A second call with the same header name replaces the value.
  • fetch: sends the stack headers first, then the content type headers, then the entry headers. A header that the entry holds replaces a stack or content type header of the same name.
  • The SDK writes these headers after yours, so an entry header cannot replace them:
    • X-User-Agent and User-Agent.
    • branch, when the stack configuration sets a branch.
  • The Get a single entry request accepts the branch header to read the entry from a branch.

Example

Read an entry from a branch (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry setHeader:@"BRANCH_UID" forKey:@"branch"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Read an entry from a branch (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.setHeader("BRANCH_UID", forKey: "branch")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

variantUid:

variantUid: requests one entry variant, by its UID or alias, on the next fetch.

NameTypeDescription
variantUid (required)NSString *

UID or alias of the entry variant to fetch.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, passing nil raises NSInvalidArgumentException, because the entry keeps its headers in a dictionary that rejects nil. Swift does not accept nil here.

Behavior

  • Client-side only. variantUid: writes the value to the x-cs-variant-uid header of this entry and makes no request.
  • fetch: sends the header with the Get single entry variant request. The API applies the variant's changes to the fields of the base entry.
  • variantUid: and variantUids: write the same header, so the later call replaces the value of the earlier one.
  • To fetch the base entry again, remove the header with the removeHeaderForKey: method and the key x-cs-variant-uid.

Note The Delivery API offers Entry Variants through an Early Access Program, so the feature may not be available on your stack. See Entry Variants.

Example

Fetch one entry variant (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry variantUid:@"VARIANT_UID"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Fetch one entry variant (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.variantUid("VARIANT_UID")
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}

Return to the base entry (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
[entry variantUid:@"VARIANT_UID"];
// Drop the variant header before the fetch.
[entry removeHeaderForKey:@"x-cs-variant-uid"];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) { return; }
    NSLog(@"%@", entry.title);
}];

Return to the base entry (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
entry.variantUid("VARIANT_UID")
// Drop the variant header before the fetch.
entry.removeHeader(forKey: "x-cs-variant-uid")
entry.fetch { (type, error) in
    guard error == nil else { return }
    print(entry.title)
}

variantUids:

variantUids: requests several entry variants, by UID or alias, on the next fetch.

NameTypeDescription
variantUids (required)NSArray *

Variant UIDs or aliases, highest priority first.

Default: Not applicable

Returns: void. Nothing. The entry keeps the setting for its next fetch.

Validation

  • There is no client-side validation. variantUids: does not check the number of values or their type.
  • An invalid value surfaces in the error argument of the completion block of the next fetch or find call.
  • In Objective-C, passing nil raises NSInvalidArgumentException, because the entry keeps its headers in a dictionary that rejects nil. Swift does not accept nil here.

Behavior

  • Client-side only. variantUids: joins the values with commas and writes the result to the x-cs-variant-uid header of this entry. It makes no request.
  • The SDK joins the text description of each element, so pass strings. An empty array writes an empty header value.
  • fetch: sends the header with the Get single entry variant request.
    • The variant listed first takes the highest priority when the API applies the variants to the fields of the base entry.
    • By default, the API accepts up to five variant UIDs or aliases in one request.
  • variantUids: and variantUid: write the same header, so the later call replaces the value of the earlier one.
  • To fetch the base entry again, remove the header with the removeHeaderForKey: method and the key x-cs-variant-uid.

Note The Delivery API offers Entry Variants through an Early Access Program, so the feature may not be available on your stack. See Entry Variants.

Example

Fetch an entry with two variants (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Entry *entry = [[stack contentTypeWithName:@"CONTENT_TYPE_UID"] entryWithUID:@"ENTRY_UID"];
// The first variant takes priority.
[entry variantUids:@[@"VARIANT_UID", @"summer_sale"]];
[entry fetch:^(ResponseType type, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entry.title);
}];

Fetch an entry with two variants (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let entry = stack.contentType(withName: "CONTENT_TYPE_UID").entry(withUID: "ENTRY_UID")
// The first variant takes priority.
entry.variantUids(["VARIANT_UID", "summer_sale"])
entry.fetch { (type, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entry.title)
}