Skip to content

Note

We're sorry, this article hasn't been completed or updated yet. We're working on finishing it as soon as possible. In case of any questions, please reach out to our Support Team.

API Interactions

The KontaktCloud handles all interactions with Kontakt.io Cloud via the Kontakt.io Proximity REST API. To obtain the client instance we can use KontaktCloudFactory:

KontaktCloud kontaktCloud = KontaktCloudFactory.create();

Info

If you decide to instantiate KontaktCloud in such a way, make sure that KontaktSDK is already initialized with the proper API key.

Alternatively you can use overloaded method that accepts the API key as a parameter:

KontaktCloud kontaktCloud = KontaktCloudFactory.create("Your API key");

Main goal of this class is to provide all API endpoints. Below you can find sample code snippet that shows how to access them:

KontaktCloud kontaktCloud = KontaktCloudFactory.create();

ActionsApi actionsApi = kontaktCloud.actions();
DevicesApi devicesApi = kontaktCloud.devices();
VenuesApi venuesApi = kontaktCloud.venues();
ConfigsApi configsApi = kontaktCloud.configs();
ManagersApi managersApi = kontaktCloud.managers();
FirmwaresApi firmwaresApi = kontaktCloud.firmwares();
ProximitiesApi proximitiesApi = kontaktCloud.proximities();
NamespacesApi namespacesApi = kontaktCloud.namespaces();
CommandsApi commandsApi = kontaktCloud.commands();
PresetsApi presetsApi = kontaktCloud.presets();

All of them are responsible for providing special components that allow us to execute endpoint-related requests both in synchronous and asynchronous mode. The idea of such a solution was to provide rich interface for managing requests in chained fashion. Every endpoint has a bunch of methods that returns proper request executors with fluent API tailored for particular set of tasks. Following this line, DevicesApi can be used for example to fetch, update, move, share or unshare devices. To make it more understandable, the code below will serve as an example. Assume we want to fetch iBeacon devices with specified start index, max result and filter query we can achieve it as follows:

Devices devices = kontaktCloud.devices().iBeacons()
        .startIndex(7)
        .maxResult(10)
        .filter("major>=155&minor<=500")
        .execute();

The example above shows synchronous way of executing a request. If you want to make an asynchronous call, please use overloaded method that accepts a CloudCallback object, e.g.:

kontaktCloud.devices().eddystones()
    .maxResult(15)
    .startIndex(3)
    .access(Access.OWNER)
    .execute(new CloudCallback<Devices>() {
      @Override public void onSuccess(Devices response, CloudHeaders headers) {
        // success
      }

      @Override public void onError(CloudError error) {
        // failure
      }
    });

Regarding to POST requests, there can be similarly handled. For instance, to create a content action for certain devices use presented piece of code:

Action createdAction = kontaktCloud.actions().createContentAction()
    .forDevices("Tx67", "QuJK", "k9hJ")
    .withMediaFile(new File(path))
    .withProximity(Proximity.NEAR)
    .execute();

Info

If synchronous request execution fails, a KontaktCloudException will be thrown. In async mode, we can simply handle an error through a callback.

The following sections describe each API endpoint in details with code examples attached.

Actions API endpoint

Interactions with actions API can be handled by ActionsApi instance that provides multiple request executors.

More detailed information can be found in the JavaDocs.

Complete list of requests that can be executed by Actions API endpoint:

  • Fetch actions.
Actions actions = kontaktCloud.actions().fetch()
      .forDevices("AxT7")
      .startIndex(4)
      .maxResult(10)
      .execute();
  • Fetch content action file.
FileData file = kontaktCloud.actions().fileOf(actionID).execute();
  • Create browser action.
Action browserAction = kontaktCloud.actions().createBrowserAction()
      .forDevices("AxT7")
      .withProximity(Proximity.NEAR)
      .withUrl("https://kontakt.io")
      .execute();
  • Update browser action.
kontaktCloud.actions().updateBrowserAction(ID)
      .withProximity(Proximity.IMMEDIATE)
      .withUrl("https://kontakt.io")
      .execute();
  • Create content action.
Action contentAction = kontaktCloud.actions().createContentAction()
      .forDevices("AxT7")
      .withProximity(Proximity.NEAR)
      .withMediaFile(new File(fileName))
      .execute();
  • Update content action.
kontaktCloud.actions().updateContentAction(ID)
      .withProximity(Proximity.IMMEDIATE)
      .withMediaFile(new File(fileName))
      .execute();
  • Delete action:
kontaktCloud.actions().delete(ID).execute();

Devices API endpoint

Interactions with devices API can be handled by DevicesApi instance that provides multiple request executors.

More detailed information can be found in the JavaDocs.

Complete list of requests that can be executed by Devices API endpoint:

  • Fetch all devices.
Devices devices = kontaktCloud.devices().fetch()
      .managerIds(managerIDs)
      .type(DeviceType.BEACON)
      .profile(DeviceProfile.IBEACON)
      .startIndex(5)
      .maxResult(10)
      .filter("major>=155&minor<=500")
      .execute();
  • Fetch devices from the URL.
Devices devices = kontaktCloud.devices().fetchFromUrl(URL).execute();
  • Fetch Eddystone devices only.
Devices eddystones = kontaktCloud.devices().eddystones()
      .withIds(eddystoneUIDs)
      .maxResult(10)
      .execute();
  • Fetch iBeacon devices only.
Devices iBeacons = kontaktCloud.devices().iBeacons()
      .withIds(iBeaconIDs)
      .maxResult(10)
      .execute();
  • Fetch device credentials.
// for single device
Credentials credentials = kontaktCloud.devices().credentials(ID).execute();

// for multiple devices
CredentialsList credentialsList = kontaktCloud.devices().credentials(IDs).execute();
  • Update device.
kontaktCloud.devices().update(ID).with(updatedDevice).execute();
  • Move devices to other manager, even from other company.
kontaktCloud.devices().move(IDs)
      .toManager(managerID)
      .toCompany(companyID)
      .execute();
  • Apply secure configs.
kontaktCloud.devices().applySecureConfigs(secureConfigs).execute();
  • Assign devices either to a manager or to a venue.
// assign to the manager
kontaktCloud.devices().assign(IDs).toManager(managerID).execute();

// assign to the venue
kontaktCloud.devices().assign(IDs).toVenue(venueID).execute();

// cannot assign both to manager and venue,
// an exception will be thrown at runtime
kontaktCloud.devices().assign(IDs)
        .toManager(managerID)
        .toVenue(venueID)
        .execute();
  • Unassign devices from the venue.
kontaktCloud.devices().unassignFromVenue(IDs).execute();
  • Share devices with managers.
kontaktCloud.devices().share(IDs)
      .toManagers(managerEmails)
      .withAccess(Access.VIEWER)
      .expirationDate(date)
      .execute();
  • Unshare devices.
kontaktCloud.devices().unshare(IDs)
      .fromManagers(managerEmails)
      .execute();

Venues API endpoint

Interactions with venues API can be handled by VenuesApi instance that provides multiple request executors.

More detailed information can be found in the JavaDocs.

Complete list of requests that can be executed by Venues API endpoint:

  • Fetch venues.
// fetch single venue
Venue venue = kontaktCloud.venues().fetch(ID).execute();

// fetch multiple venues
Venues venues = kontaktCloud.venues().fetch()
      .managerIds(managerIDs)
      .startIndex(5)
      .maxResult(10)
      .execute();
  • Fetch venue's image file.
FileData imageFile = kontaktCloud.venues().imageOf(venueID).execute();
  • Create new venue.
Venue venue = Venue.builder()
      .name("Kontakt.io office")
      .description("Beacon valley")
      .build();
kontaktCloud.venues().create(venue)
      .withImageFile(new File(fileName))
      .execute();
  • Update venue.
kontaktCloud.venues().update(ID).with(updatedVenue).execute();
  • Delete venue.
kontaktCloud.venues().delete(ID).execute();
  • Share venues with managers.
kontaktCloud.venues().share(IDs)
      .toManagers(managerEmails)
      .withAccess(Access.VIEWER)
      .expirationDate(date)
      .execute();
  • Unshare venues.
kontaktCloud.venues().unshareVenues(IDs)
      .fromManagers(managerEmails)
      .execute();

Configs API endpoint

Interactions with configs API can be handled by ConfigsApi instance that provides multiple request executors.

More detailed information can be found in the JavaDocs.

Complete list of requests that can be executed by Configs API endpoint:

  • Fetch configs.
Configs configs = kontaktCloud.configs().fetch()
      .type(DeviceType.BEACON)
      .profile(DeviceProfile.EDDYSTONE)
      .maxResult(15)
      .execute();
  • Fetch secure configs.
Configs configs = kontaktCloud.configs().secure()
      .withIds("7HuT", "2Fge", "dFGh")
      .maxResult(10)
      .execute();
  • Create new config.
Config config = Config.builder().major(532).minor(111).build();
kontaktCloud.configs().create(config)
      .forDevices("AxT7", "GVy6", "9KiJ")
      .withType(DeviceType.BEACON)
      .execute();
  • Delete pending configs.
kontaktCloud.configs().delete(IDs).execute();

Managers API endpoint

Interactions with managers API can be handled by ManagersApi instance that provides multiple request executors.

More detailed information can be found in the JavaDocs.

Complete list of requests that can be executed by Managers API endpoint:

  • Fetch managers.
// fetch single manager
Manager manager = kontaktCloud.managers().fetch(ID).execute();

// fetch multiple managers
Managers managers = kontaktCloud.managers().fetch()
      .subordinatesOf(supervisorID)
      .execute();
  • Create new manager.
Manager manager = Manager.builder()
      .firstName("Superb")
      .lastName("Kontakter")
      .email("superb.kontakter@kontakt.io")
      .role(Manager.Role.SUPERUSER)
      .build();
kontaktCloud.managers().create(manager).execute();
  • Update manager.
Manager updatedManager = Manager.builder()
      .email("admin.kontakter@kontakt.io")
      .role(Manager.Role.ADMIN)
      .build();
kontaktCloud.managers().update(ID).with(updatedManager).execute();
  • Delete manager.
kontaktCloud.managers().delete(ID).execute();

Firmwares API endpoint

Interactions with firmwares API can be handled by FirmwaresApi instance that provides multiple request executors.

More detailed information can be found in the JavaDocs.

Complete list of requests that can be executed by Firmwares API endpoint:

  • Fetch single firmware by name.
String name = "3.1";
Firmware firmware = kontaktCloud.firmwares().fetch(name)
      .forDeviceType(DeviceType.BEACON)
      .execute();
  • Fetch firmwares for specified devices.
Firmwares firmwares = kontaktCloud.firmwares().fetch()
      .forDevices("4DgT")
      .execute();
  • Fetch firmware file.
String name = "3.1";
FileData firmwareFile = kontaktCloud.firmwares().fileOf(name)
      .forDeviceType(DeviceType.BEACON)
      .execute();
  • Schedule firmware update.
kontaktCloud.firmwares().scheduleUpdate()
      .forDevices("4DgT", "8JkU")
      .withVersion("4.0")
      .execute();
  • Unschedule firmware update.
kontaktCloud.firmwares().unscheduleUpdate()
      .forDevices("4DgT", "8JkU")
      .execute();

Proximities API endpoint

Interactions with proximities API can be handled by ProximitiesApi instance.

More detailed information can be found in the JavaDocs.

By using Proximities API endpoint we can fetch secure proximities mapping:

Proximities proximities = kontaktCloud.proximities().fetch()
      .startIndex(4)
      .maxResult(10)
      .execute();

Namespaces API endpoint

Interactions with namespaces API can be handled by NamespacesApi instance.

More detailed information can be found in the JavaDocs.

By using Namespaces API endpoint we can fetch secure namespaces mapping:

Namespaces namespaces = kontaktCloud.namespaces().fetch()
      .startIndex(4)
      .maxResult(10)
      .execute();

Commands API endpoint

Interactions with commands API can be handled by CommandsApi instance.

More detailed information can be found in the JavaDocs.

By using Commands API endpoint we can fetch secure commands:

SecureCommands commands = kontaktCloud.commands().fetch()
      .forDevices("34Gh", "5Gk9", "d5Gv")
      .withType(SecureCommandType.BOOTLOADER)
      .startIndex(5)
      .maxResult(15)
      .execute();

Presets API endpoint

Interactions with presets API can be handled by PresetsApi instance.

More detailed information can be found in the JavaDocs.

By using Presets API endpoint we can fetch presets:

// fetch single preset
Preset preset = kontaktCloud.presets().fetch(name).execute();

// fetch multiple presets
Presets presets = kontaktCloud.presets().fetch().execute();