This guide will show you how to get started using our Swift SDK to consume content.

Contentful's Content Delivery API (CDA) is a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location by using our global CDN.

We publish SDKs for various languages to make developing applications easier.

Requirements

This tutorial assumes that you understand the Contentful data model.

Authentication

For every request, clients need to provide an API key, which is created per space and used to delimit applications and content classes.

You can create an access token using the Contentful web app or the Content Management API.

Install the SDK

There are different ways to integrate the SDK into your own apps, described in detail in the README for the SDK. This guide will use CocoaPods, the dependency manager for Cocoa projects, which helps you keep the SDK up-to-date:

Create a Podfile for your project which adds Contentful as a dependency for you project. You can specify a particular version(s) of the SDK using the various operators that Cocoapods offers

use_frameworks!

target 'Your Xcode targets name' do
  pod 'Contentful'
end

Initialize the client

You need an API key and a space ID to initialize a client. You can use the API key and space ID pre-filled below from our example space or replace them with your own values.

let spaceId = "<space_id>"
let token = "<access_token>"

let client = Client(spaceId: spaceId, accessToken: token)

Accessing data

The Client class manages all requests to the API, and now that you have initialized a Client instance, you can fetch entries. Note that you must retain your Client instance as a property (instance variable) in your application so that asynchronous callbacks are not released by the system before execution.

Fetch one entry:

client.fetchEntry(id: "nyancat") { (result: Result<Entry>) in
    switch result {
    case .success(let nyanCat):
        print(nyanCat.id) // Prints "nyanCat" to console.

    case .error(let error):
        print("Oh no something went wrong: \(error)")
    }
}

Fetch all entries with content_type = "cat"

let query = Query(where: "content_type", .equals("cat"))

client.fetchEntries(with: query) { (result: Result<ArrayResponse<Entry>>) in
    switch result {
    case .success(let entriesArrayResponse):
        let cats = entriesArrayResponse.items

        // Do stuff with cat entries.

    case .error(let error):
        print("Oh no something went wrong: \(error)")
    }
}

A more refined approach

While the above approach is great for quickly fetching data from the API, it can also be useful to retrieve already serialized instances of your own model classes. The EntryModellable protocol enables said mapping. Let's get started by implementing a model class, Cat, which will conform to our EntryModellable protocol:

final class Cat: EntryModellable {

    static let contentTypeId: String = "cat"

    let id: String
    let localeCode: String
    let color: String?
    let name: String?
    let lives: Int?
    let likes: [String]?

    // Relationship fields.
    var bestFriend: Cat?

    init(entry: Entry) {
        self.id         = entry.id
        self.localeCode = entry.localeCode

        self.name       = entry.fields["name"] as? String
        self.color      = entry.fields["color"] as? String
        self.likes      = entry.fields["likes"] as? [String]
        self.lives      = entry.fields["lives"] as? Int
    }

    func populateLinks(from cache: [FieldName: Any]) {
        self.bestFriend = cache["bestFriend"] as? Cat
    }
}

Now take a look at what a query on our Cat class would look like. In particular, we'll create a query where the color field of our cat is set to "gray".

let query = QueryOn<Cat>(where: "fields.color", .equals("gray"))

// Note the type in the asynchronously returned result: An `MappedArrayResponse` with `Cat` as the item type.
client.fetchMappedEntries(with: query) { (result: Result<MappedArrayResponse<Cat>>) in
    switch result {
    case .success(let catsResponse):
        guard let cat = catsResponse.items.first else { return }

        print(cat.color!) // Prints "gray" to console.

    case .error(let error):
        print("Oh no something went wrong: \(error)")
    }
}