Contentstack

View as Markdown

Contentstack

Contentstack is the entry point of the iOS Delivery SDK. It has class methods only, so you call them on the class and never create a Contentstack object. Use this class to

  • create a Stack from your API key, delivery token, and environment
  • create a stack with a Config that sets the region, host, branch, TLS delegate, or early access features
  • cancel the queued operations of a stack

cancelAllRequestsOfStack:

cancelAllRequestsOfStack: cancels the operations that wait in the queue of the network session of a stack.

NameTypeDescription
stack (required)Stack *

Stack whose queued operations to cancel.

Default: Not applicable

Returns: void. Nothing.

Validation

  • There is no client-side validation. A nil stack does nothing.

Behavior

  • Client-side only. cancelAllRequestsOfStack: makes no request.
  • It cancels the operations in the operation queue of the network session of stack. The session runs completion handling on that queue. It does not cancel the network tasks that the session runs.
  • Other stacks keep their requests, because each stack has its own network session.

Example

Basic usage: cancel when the user leaves a screen (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
__block BOOL screenClosed = NO;
[stack sync:^(SyncStack *syncStack, NSError *error) {
    if (screenClosed) { return; }
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu items", (unsigned long)syncStack.items.count);
}];

// Later, when the user leaves the screen
screenClosed = YES;
[Contentstack cancelAllRequestsOfStack:stack];

Basic usage: cancel when the user leaves a screen (Swift)

import Contentstack

final class SyncScreen {
    let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
    var screenClosed = false

    func load() {
        stack.sync { [weak self] (syncStack, error) in
            guard let self = self, !self.screenClosed else { return }
            if let error = error as NSError? {
                print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
                return
            }
            print("\(syncStack?.items?.count ?? 0) items")
        }
    }

    func close() {
        screenClosed = true
        Contentstack.cancelAllRequests(of: stack)
    }
}

stackWithAPIKey:accessToken:environmentName:

stackWithAPIKey:accessToken:environmentName: creates a stack that reads the content published to one environment, with the default configuration.

NameTypeDescription
apiKey (required)NSString *

API key of the stack.

Default: Not applicable
token (required)NSString *

Delivery token of the environment.

Default: Not applicable
environmentName (required)NSString *

Environment to read published content from.

Default: Not applicable

Returns: Stack. A new stack with the default configuration.

Validation

  • There is no client-side validation of the values. An empty or wrong API key, delivery token, or environment surfaces in the error argument of the completion block of the first request.
  • A nil apiKey or token raises NSInvalidArgumentException here, because the SDK stores both in a header dictionary that rejects nil values.
  • A nil environmentName raises NSInvalidArgumentException at the first fetch or find call, because that call stores the environment in a parameter dictionary.

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

Behavior

  • Client-side only. stackWithAPIKey:accessToken:environmentName: makes no request.
  • It calls the stackWithAPIKey:accessToken:environmentName:config: method with a new Config. The stack therefore uses the US region, the host cdn.contentstack.io, no branch, and no early access features.
  • The SDK sends apiKey in the api_key header and token in the access_token header of every request. The apiKey, accessToken, and environment properties of the stack return the three values.
  • Each call creates a new stack with its own network session.

Example

Basic usage: create a stack and 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);
}];

Basic usage: create a stack and 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)
}

stackWithAPIKey:accessToken:environmentName:config:

stackWithAPIKey:accessToken:environmentName:config: creates a stack that reads the content published to one environment, with the region, host, branch, and other settings of a Config.

NameTypeDescription
apiKey (required)NSString *

API key of the stack.

Default: Not applicable
accessToken (required)NSString *

Delivery token of the environment.

Default: Not applicable
environmentName (required)NSString *

Environment to read published content from.

Default: Not applicable
config (required)Config *

Region, host, branch, delegate, and early access settings.

Default: Not applicable

Returns: Stack. A new stack that uses the given configuration.

Validation

  • There is no client-side validation of the values. An empty or wrong API key, delivery token, or environment surfaces in the error argument of the completion block of the first request.
  • A nil apiKey or accessToken raises NSInvalidArgumentException here, because the SDK stores both in a header dictionary that rejects nil values.
  • A nil environmentName raises NSInvalidArgumentException at the first fetch or find call, because that call stores the environment in a parameter dictionary.
  • A nil config leaves the stack with no host and no API version, so every request fails. The parameter is non-null, so pass a Config object.

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

Behavior

  • Client-side only. stackWithAPIKey:accessToken:environmentName:config: makes no request.
  • The stack keeps a reference to the Config you pass, not a copy. A later change to host, region, or branch applies to the next request of the stack. A later change to delegate or setEarlyAccess has no effect. See the Config class page for when the stack reads each setting.
  • The SDK sends apiKey in the api_key header and accessToken in the access_token header of every request.
  • Each call creates a new stack with its own network session.

Example

All parameters: create a stack for a branch in the EU region (Objective-C)

#import <Contentstack/Contentstack.h>

Config *config = [[Config alloc] init];
config.region = EU;
config.branch = @"BRANCH_UID";
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT" config:config];
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(@"%@ from %@", entry.title, stack.hostURL);
}];

All parameters: create a stack for a branch in the EU region (Swift)

import Contentstack

let config = Config()
config.region = .EU
config.branch = "BRANCH_UID"
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT", config: config)
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) from \(stack.hostURL)")
}

Custom host: send requests to your own delivery host (Objective-C)

#import <Contentstack/Contentstack.h>

Config *config = [[Config alloc] init];
// A bare host name. The SDK adds https:// and the API version.
config.host = @"CUSTOM_HOST";
Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT" config:config];
[[stack assetLibrary] fetchAll:^(ResponseType type, NSArray<Asset *> *result, NSError *error) {
    if (error) { return; }
    NSLog(@"%lu assets", (unsigned long)result.count);
}];

Custom host: send requests to your own delivery host (Swift)

import Contentstack

let config = Config()
// A bare host name. The SDK adds https:// and the API version.
config.host = "CUSTOM_HOST"
let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT", config: config)
stack.assetLibrary().fetchAll { (type, result, error) in
    guard error == nil else { return }
    print("\(result?.count ?? 0) assets")
}