Taxonomy

View as Markdown

Taxonomy

A taxonomy arranges the content of a stack into a hierarchy of terms that entries carry. Use the Taxonomy class to find the published entries tagged with a term, across every content type of the stack, in one request.

Get the object from the taxonomy method of Stack, which takes no arguments. Each call returns a new Taxonomy object. The object holds no taxonomy UID. You name the taxonomy inside each condition, as the field path taxonomies.<TAXONOMY_UID>.

addHeadersWithDictionary:

addHeadersWithDictionary: sets several HTTP headers at once that the SDK sends with the requests of this taxonomy.

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

Header names mapped to the values to send.

Default: Not applicable

Returns: void. Nothing. The taxonomy keeps the setting for its next query request.

Validation

  • There is no client-side validation. A nil or empty dictionary changes nothing.
  • An invalid header surfaces in the error argument of the completion block of the next findTaxonomy: call.

Behavior

  • Client-side only. addHeadersWithDictionary: copies each pair into the headers of this taxonomy and makes no request.
  • A name that the object already holds gets the new value. Headers that the dictionary does not name stay as they are.
  • findTaxonomy: sends the headers of this taxonomy with every query that the taxonomy created through query, including queries created before the change.
  • A header that a query sets with its own setHeader:forKey: replaces the taxonomy header of the same name for that query.
  • fetch:completion: on this taxonomy does not send these headers.
  • A header with the same name as a stack header, such as access_token, replaces the stack value for these requests.
  • When you set Config.branch, the SDK writes it to the branch header after your headers, so it replaces a branch header that you set here.

Example

Set a variant and a branch in one call (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
[taxonomy addHeadersWithDictionary:@{@"x-cs-variant-uid": @"VARIANT_UID", @"branch": @"BRANCH_UID"}];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];

Set a variant and a branch in one call (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
taxonomy.addHeaders(with: ["x-cs-variant-uid": "VARIANT_UID", "branch": "BRANCH_UID"])
let query = taxonomy.query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (type, result, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(result?.getResult()?.count ?? 0) entries")
}

fetch:completion:

fetch:completion: requests the published entries tagged with taxonomy terms, with the query parameters you pass, and hands the entries value of the response to the completion block.

NameTypeDescription
paramsNSDictionary<NSString *, id> *

Query parameters to send, such as query and locale.

Default: nil
completionBlock (required)void (^)(NSDictionary<NSString *, NSString *> *, NSError *)

Receives the entries value, or an error.

Default: Not applicable

Returns: void. Nothing. The completion block receives the result.

Validation

  • There is no client-side validation. fetch:completion: sends every key of params as given.
  • 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.
  • When the response has no entries dictionary, the completion block receives an NSError with domain Error, code -4001, and the reason under userInfo[@"error"]. The Known issue above describes when this happens.

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

Behavior

  • One call sends one Get all entries with defined taxonomies request (GET /taxonomies/entries).
  • The SDK adds the stack environment in the environment parameter. A params key named environment replaces it.
  • The SDK encodes a dictionary under the query key of params as JSON in the query parameter. Every other key goes into the query string as given.
  • The request carries the stack headers only. Headers that you set on this taxonomy with setHeader:forKey: do not reach it.
  • The request always goes to the network. fetch:completion: has no cache policy.

Example

Request the entries tagged with a term (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
NSDictionary *params = @{@"query": @{@"taxonomies.TAXONOMY_UID": @"TERM_UID"}, @"locale": @"en-us"};
[taxonomy fetch:params completion:^(NSDictionary<NSString *, NSString *> *entries, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%@", entries);
}];

Request the entries tagged with a term (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let params: [String: Any] = ["query": ["taxonomies.TAXONOMY_UID": "TERM_UID"], "locale": "en-us"]
taxonomy.fetch(params) { (entries, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print(entries ?? [:])
}

Error handling: tell an unexpected response from an API rejection (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
[[stack taxonomy] fetch:nil completion:^(NSDictionary<NSString *, NSString *> *entries, NSError *error) {
    if ([error.domain isEqualToString:@"Error"]) {
        // The response arrived, but entries was not a dictionary.
        NSLog(@"%@", error.userInfo[@"error"]);
        return;
    }
    if (error) { return; }
    NSLog(@"%@", entries);
}];

Error handling: tell an unexpected response from an API rejection (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
stack.taxonomy().fetch(nil) { (entries, error) in
    if let error = error as NSError?, error.domain == "Error" {
        // The response arrived, but entries was not a dictionary.
        print(error.userInfo["error"] ?? "")
        return
    }
    guard error == nil else { return }
    print(entries ?? [:])
}

query

query creates a Query that finds the published entries tagged with taxonomy terms, across every content type of the stack.

Returns: Query. A new query object for this taxonomy.

Validation

  • There is no client-side validation. query makes no request.
  • Errors come from the findTaxonomy: call that follows, not from query. Its completion block receives them.

Behavior

  • Client-side only. Each call returns a new Query with no conditions, so conditions on one query do not reach another.
  • findTaxonomy: sends the Get all entries with defined taxonomies request (GET /taxonomies/entries). The SDK encodes the conditions as JSON in the query parameter and adds the stack environment in the environment parameter.
  • The query keeps a reference to this taxonomy. findTaxonomy: reads the taxonomy headers when it sends the request, so a header that you set on the taxonomy after query still applies.
  • A header that the query sets with its own setHeader:forKey: replaces the taxonomy header of the same name for that query.
  • The SDK has no method for the hierarchy operators (Equal and Below, Below, Equal and Above, Above). Use whereKey:equalTo: instead.
  • whereKey:equalTo: stores a dictionary value as given, so you can pass a hierarchy operator dictionary as the value. The third example below shows this.

Example

Find the entries tagged with a term (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack taxonomy] query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    for (Entry *entry in [result getResult]) {
        NSLog(@"%@ %@", entry.uid, entry.title);
    }
}];

Find the entries tagged with a term (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.taxonomy().query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (type, result, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    for entry in result?.getResult() ?? [] {
        print(entry.uid, entry.title)
    }
}

Match a term in either of two taxonomies (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
Query *colorQuery = [taxonomy query];
[colorQuery whereKey:@"taxonomies.color" equalTo:@"red"];
Query *sizeQuery = [taxonomy query];
[sizeQuery whereKey:@"taxonomies.size" equalTo:@"small"];
Query *query = [taxonomy query];
[query orWithSubqueries:@[colorQuery, sizeQuery]];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
    if (error) { return; }
    NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];

Match a term in either of two taxonomies (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
let colorQuery = taxonomy.query()
colorQuery.whereKey("taxonomies.color", equalTo: "red")
let sizeQuery = taxonomy.query()
sizeQuery.whereKey("taxonomies.size", equalTo: "small")
let query = taxonomy.query()
query.or(withSubqueries: [colorQuery, sizeQuery])
query.findTaxonomy { (type, result, error) in
    guard error == nil else { return }
    print("\(result?.getResult()?.count ?? 0) entries")
}

Match a term and the two levels of terms below it (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Query *query = [[stack taxonomy] query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@{@"$eq_below": @"TERM_UID", @"levels": @2}];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
    if (error) { return; }
    NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];

Match a term and the two levels of terms below it (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let query = stack.taxonomy().query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: ["$eq_below": "TERM_UID", "levels": 2])
query.findTaxonomy { (type, result, error) in
    guard error == nil else { return }
    print("\(result?.getResult()?.count ?? 0) entries")
}

removeHeaderForKey:

removeHeaderForKey: removes one header that you set on this taxonomy, so later requests no longer send it.

NameTypeDescription
headerKey (required)NSString *

Name of the header to remove.

Default: Not applicable

Returns: void. Nothing. The taxonomy keeps the setting for its next query request.

Validation

  • There is no client-side validation. A name that this taxonomy does not hold, or nil, changes nothing.
  • An invalid header surfaces in the error argument of the completion block of the next findTaxonomy: call.

Behavior

  • Client-side only. removeHeaderForKey: deletes the header from this taxonomy and makes no request.
  • It removes only headers set on this taxonomy. Stack headers such as api_key and access_token, and headers set on an entry or a query, stay in place.
  • findTaxonomy: sends the headers of this taxonomy with every query that the taxonomy created through query, including queries created before the change.

Example

Stop sending a variant header (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
[taxonomy setHeader:@"VARIANT_UID" forKey:@"x-cs-variant-uid"];
[taxonomy removeHeaderForKey:@"x-cs-variant-uid"];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];

Stop sending a variant header (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
taxonomy.setHeader("VARIANT_UID", forKey: "x-cs-variant-uid")
taxonomy.removeHeader(forKey: "x-cs-variant-uid")
let query = taxonomy.query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (type, result, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(result?.getResult()?.count ?? 0) entries")
}

setHeader:forKey:

setHeader:forKey: sets one HTTP header that the SDK sends with the requests of this taxonomy.

NameTypeDescription
headerValue (required)NSString *

Value of the header to send.

Default: Not applicable
headerKey (required)NSString *

Name of the header to send.

Default: Not applicable

Returns: void. Nothing. The taxonomy keeps the setting for its next query request.

Validation

  • There is no client-side validation. The SDK stores an empty string as given.
  • A nil headerValue or headerKey raises NSInvalidArgumentException, because the SDK stores the pair in a mutable dictionary that rejects nil. Both parameters are nonnull, so the compiler warns on a literal nil.
  • An invalid header surfaces in the error argument of the completion block of the next findTaxonomy: call.

Behavior

  • Client-side only. setHeader:forKey: stores the pair on this taxonomy and makes no request. A second call with the same headerKey replaces the value.
  • findTaxonomy: sends the headers of this taxonomy with every query that the taxonomy created through query, including queries created before the change.
  • A header that a query sets with its own setHeader:forKey: replaces the taxonomy header of the same name for that query.
  • fetch:completion: on this taxonomy does not send these headers.
  • A header with the same name as a stack header, such as access_token, replaces the stack value for these requests.
  • The Get entries by taxonomy with variants request reads variant UIDs from the x-cs-variant-uid header. The API then applies that variant to each matching entry.

Example

Apply a variant to the entries (Objective-C)

#import <Contentstack/Contentstack.h>

Stack *stack = [Contentstack stackWithAPIKey:@"API_KEY" accessToken:@"DELIVERY_TOKEN" environmentName:@"ENVIRONMENT"];
Taxonomy *taxonomy = [stack taxonomy];
[taxonomy setHeader:@"VARIANT_UID" forKey:@"x-cs-variant-uid"];
Query *query = [taxonomy query];
[query whereKey:@"taxonomies.TAXONOMY_UID" equalTo:@"TERM_UID"];
[query findTaxonomy:^(ResponseType type, QueryResult *result, NSError *error) {
    if (error) {
        NSLog(@"Error %ld: %@", (long)error.code, error.userInfo[@"error_message"]);
        return;
    }
    NSLog(@"%lu entries", (unsigned long)[result getResult].count);
}];

Apply a variant to the entries (Swift)

import Contentstack

let stack = Contentstack.stack(withAPIKey: "API_KEY", accessToken: "DELIVERY_TOKEN", environmentName: "ENVIRONMENT")
let taxonomy = stack.taxonomy()
taxonomy.setHeader("VARIANT_UID", forKey: "x-cs-variant-uid")
let query = taxonomy.query()
query.whereKey("taxonomies.TAXONOMY_UID", equalTo: "TERM_UID")
query.findTaxonomy { (type, result, error) in
    if let error = error as NSError? {
        print("Error \(error.code): \(error.userInfo["error_message"] ?? "")")
        return
    }
    print("\(result?.getResult()?.count ?? 0) entries")
}