Skip to content

5. API client

The Kontakt.io Cloud API provides a series of resources to query/update our Cloud Services. Every information that you can either access or modify in Kontakt.io Web Panel is also available through API for our backend.

Class responsible for communication with that API is the KTKCloudClient.

Initializing an API client

There are few ways how you can get an API client object.

First of all, you can just make a new instance of KTKCloudClient:

let apiClient1 = KTKCloudClient()

If you need to use your own URLSessionConfiguration, there is a designated initializer for that:

let apiClient2 = KTKCloudClient(sessionConfiguration: yourURLSessionConfiguration)

Alternatively, you can always take advantage of a shared instance (singleton), normally used for SDK's API calls, but suitable for any ad-hoc requests as well:

let apiClient3 = KTKCloudClient.sharedInstance()

Making an API call

Most data that you can get from or modify through an API call has an equivalent in one of SDK classes. All classes representing objects from the API conform to KTKCloudModel protocol.

Thanks to that there is no need to make a direct call to an API endpoint (although there is a possibility to do just that), but instead you just provide a type of data you're interested in or you would like to update, additional parameters, if needed, and a completion block/closure to handle an API response or a error.

Exemple: getting pending configurations for your beacons

let parameters = ["deviceType": "beacon"]
KTKCloudClient.sharedInstance().getObjects(KTKDeviceConfiguration.self, parameters: parameters) { response, error in
    if let ktkError = KTKCloudErrorFromError(error) {
        print(ktkError.debugDescription)
    } else if let configs = response?.objects as? [KTKDeviceConfiguration] {
        for config in configs {
            // Do something with a config
        }
    }
}

More examples will be available later.

API response

Every API response is represented as an KTKKontaktResponse. The actual data that you will probably be interested in is available in objects property. Please keep in mind you will need to typecast it as a proper class, depending on what exactly you've asked the API for.

Some API responses might contain a lot of data and because of that they are paginated. KTKKontaktResponse objects have a number of helper properties, like nextResultsURL, previousResultsURL, startIndex, etc., that will help you with handling large sets of data coming from the API. For more details please check KTKKontaktResponse documentation.