Disruptive Documentation Beta

Structure Disruptive

public struct Disruptive

This is the core of the Disruptive Swift API, and implements the majority of the Disruptive Technologies REST API endpoints.

The most straight-forward usage is to create one single shared instance of this, and use it across the entire app (although you can create multiple instances if you need to). When initialized with an Authenticator, a Disruptive instance will keep an access token up-to-date automatically, so all requests are authenticated.

Initializers

init(authenticator:​base​URL:​emulator​Base​URL:​)

public init(authenticator: Authenticator, baseURL: String = Disruptive.defaultBaseURL, emulatorBaseURL: String = Disruptive.defaultBaseEmulatorURL)

Initializes a Disruptive instance.

Parameters

authenticator Authenticator

Used to authenticate against the Disruptive Technologies REST API. It is recommended to pass an OAuth2Authenticator instance to this parameter.

base​URL String

Optional parameter. The base URL for the REST API. The default value is Disruptive.defaultBaseURL.

Properties

default​Base​URL

let defaultBaseURL = "https://api.disruptive-technologies.com/v2/"

The default base URL for the Disruptive Technologies REST API in the production environment.

default​Base​Emulator​URL

let defaultBaseEmulatorURL = "https://emulator.disruptive-technologies.com/v2/"

The default base URL for the Disruptive Technologies emulator REST API in the production environment.

default​Auth​URL

let defaultAuthURL = "https://identity.disruptive-technologies.com/oauth2/token"

The default base URL for authenticating against the Disruptive Technologies REST API in the production environment.

base​URL

let baseURL: String

The base URL for the Disruptive Technologies REST API.

emulator​Base​URL

let emulatorBaseURL: String

The base URL for the Disruptive Technologies emulator REST API.

logging​Enabled

var loggingEnabled = false

Whether or not the DisruptiveAPI should log to the console. Defaults to false.

authenticator

let authenticator: Authenticator

The authentication mechanism used by Disruptive. This will be checked to see if it has a non-expired access token before every request is sent to the Disruptive backend. If no non-expired access token were found the refreshAccessToken method will be called before attempting to send the request.

Methods

get​All​Data​Connectors(project​ID:​completion:​)

public func getAllDataConnectors(projectID: String, completion: @escaping (_ result: Result<[DataConnector], DisruptiveError>) -> ())

Gets all the Data Connectors that are available in a specific project.

This will handle pagination automatically and send multiple network requests in the background if necessary. If a lot of Data Connectors are expected to be in the project, it might be better to load pages of Data Connectors as they're needed using the getDataConnectorsPage function instead.

Parameters

project​ID String

The identifier of the project to get Data Connectors from.

completion @escaping (_ result:​ Result<[Data​Connector], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain an array of DataConnectors. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[DataConnector], DisruptiveError>

get​Data​Connectors​Page(project​ID:​page​Size:​page​Token:​completion:​)

public func getDataConnectorsPage(projectID: String, pageSize: Int = 100, pageToken: String?, completion: @escaping (_ result: Result<(nextPageToken: String?, dataConnectors: [DataConnector]), DisruptiveError>) -> ())

Gets one page of Data Connectors.

Useful if a lot of Data Connectors are expected in the specified project. This function provides better control for when to get Data Connectors and how many to get at a time so that Data Connectors are only fetch when they are needed. This can also improve performance, at a cost of convenience compared to the getAllDataConnectors function.

Parameters

project​ID String

The identifier of the project to get Data Connectors from.

page​Size Int

The maximum number of Data Connectors to get for this page. The maximum page size is 100, which is also the default

page​Token String?

The token of the page to get. For the first page, set this to nil. For subsequent pages, use the nextPageToken received when getting the previous page.

completion @escaping (_ result:​ Result<(next​Page​Token:​ String?, data​Connectors:​ [Data​Connector]), Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain a tuple with both an array of DataConnectors, as well as the token for the next page. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<(nextPageToken: String?, dataConnectors: [DataConnector]), DisruptiveError>

get​Data​Connector(project​ID:​data​Connector​ID:​completion:​)

public func getDataConnector(projectID: String, dataConnectorID: String, completion: @escaping (_ result: Result<DataConnector, DisruptiveError>) -> ())

Gets a specific Data Connector within a project by its identifier.

Parameters

project​ID String

The identifier of the project to get the Data Connector from.

data​Connector​ID String

The identifier of the Data Connector to get within the specified project.

completion @escaping (_ result:​ Result<Data​Connector, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the DataConnector. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<DataConnector, DisruptiveError>

create​Data​Connector(project​ID:​display​Name:​push​Type:​event​Types:​labels:​is​Active:​completion:​)

public func createDataConnector(projectID: String, displayName: String, pushType: DataConnector.PushType, eventTypes: [EventType], labels: [String] = [], isActive: Bool = true, completion: @escaping (_ result: Result<DataConnector, DisruptiveError>) -> ())

Creates a new Data Connector. See the Data Connectors guide on the developer website to learn more about how Data Connectors work, and how to set up an external service to receive the events that are sent out by a Data Connector.

Parameters

project​ID String

The identifier of the project to create the Data Connector in.

display​Name String

The display name to give the Data Connector.

push​Type Data​Connector.​Push​Type

The mechanism to use to push events to an external service. This will also include the parameters to configure the push mechanism.

event​Types [Event​Type]

The event types that the Data Connector will send to the external service.

labels [String]

The labels to be included along with the events. If a device that an event originates from has a label that is not included in this list, it will not be included in the event from the Data Connector. Note that if you want the display name of the device to be included in the events to the external service, you need to include the name label in this list. The default value of this parameter is an empty list, meaning no labels will be included.

is​Active Bool

Whether or not the Data Connector should start in the active state. This can be changed later by calling the updateDataConnector function.

completion @escaping (_ result:​ Result<Data​Connector, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the DataConnector (along with its generated identifier). If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<DataConnector, DisruptiveError>

update​Data​Connector(project​ID:​data​Connector​ID:​display​Name:​http​Push:​is​Active:​event​Types:​labels:​completion:​)

public func updateDataConnector(projectID: String, dataConnectorID: String, displayName: String? = nil, httpPush: (url: String?, signatureSecret: String?, headers: [String: String]?)? = nil, isActive: Bool? = nil, eventTypes: [EventType]? = nil, labels: [String]? = nil, completion: @escaping (_ result: Result<DataConnector, DisruptiveError>) -> ())

Updates the configuration of a Data Connector. Only the parameters that are set will be updated, and the remaining will be left unchanged.

Examples:

// Deactivates a Data Connector by only using the `active` parameter
disruptive.updateDataConnector(
    projectID       : "<PROJECT_ID>",
    dataConnectorID : "<DC_ID>",
    active          : false)
{ result in
    ...
}
  
// Updates the signature secret of a Data Connector, and nothing else
disruptive.updateDataConnector(
    projectID       : "<PROJECT_ID>",
    dataConnectorID : "<DC_ID>",
    httpPush        : (url: nil, signatureSecret: "NEW_SECRET", headers: nil))
{ result in
    ...
}

Parameters

project​ID String

The identifier of the project the Data Connector to update is in.

data​Connector​ID String

The identifier of the Data Connector to update.

display​Name String?

The new display name to use for the Data Connector. Will be ignored if not set (or nil). Defaults to nil.

http​Push (url:​ String?, signature​Secret:​ String?, headers:​ [String:​ String]?)?

The new configuration of the httpPush pushType. Only the non-nil tuple values will actually be set. Will be ignored the whole httpPush argument is not set (or nil). Defaults to nil.

is​Active Bool?

The new active status of the Data Connector. Will be ignored if not set (or nil). Defaults to nil.

event​Types [Event​Type]?

The new list of event types the Data Connector will send out. Will be ignored if not set (or nil). Defaults to nil.

labels [String]?

The new labels that will be included for every event pushed to an external service by the Data Connector. Will be ignored if not set (or nil). Note: if you want the display name of the device to be included in the events to the external service, you need to include the name label in this list. The default value of this parameter is nil.

completion @escaping (_ result:​ Result<Data​Connector, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the updated DataConnector. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<DataConnector, DisruptiveError>

delete​Data​Connector(project​ID:​data​Connector​ID:​completion:​)

public func deleteDataConnector(projectID: String, dataConnectorID: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Deletes a Data Connector.

Parameters

project​ID String

The identifier of the project to delete the Data Connector from.

data​Connector​ID String

The identifier of the Data Connector to delete.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

get​Data​Connector​Metrics(project​ID:​data​Connector​ID:​completion:​)

public func getDataConnectorMetrics(projectID: String, dataConnectorID: String, completion: @escaping (_ result: Result<DataConnector.Metrics, DisruptiveError>) -> ())

Retrieves the metrics for the past 3 hours for a Data Connector.

Parameters

project​ID String

The identifier of the project to delete the Data Connector from.

data​Connector​ID String

The identifier of the Data Connector to delete.

completion @escaping (_ result:​ Result<Data​Connector.​Metrics, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the DataConnector.Metrics. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<DataConnector.Metrics, DisruptiveError>

sync​Data​Connector(project​ID:​data​Connector​ID:​completion:​)

public func syncDataConnector(projectID: String, dataConnectorID: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Synchronizes a Data Connector with the external service. When this is called, the last known event for each event type of every device in the project will be re-pushed to the external service.

Parameters

project​ID String

The identifier of the project the Data Connector to synchronize is in.

data​Connector​ID String

The identifier of the Data Connector to synchronize.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

get​All​Devices(project​ID:​query:​device​IDs:​device​Types:​label​Filters:​order​By:​completion:​)

public func getAllDevices(projectID: String, query: String? = nil, deviceIDs: [String]? = nil, deviceTypes: [Device.DeviceType]? = nil, labelFilters: [String: String]? = nil, orderBy: (field: String, ascending: Bool)? = nil, completion: @escaping (_ result: Result<[Device], DisruptiveError>) -> ())

Gets all the devices in a specific project (including emulated devices).

This will handle pagination automatically and send multiple network requests in the background if necessary. If a lot of devices are expected to be in the project, it might be better to load pages of devices as they're needed using the getDevicesPage function instead.

Examples:

// Get all the devices in the project
disruptive.getAllDevices(projectID: "<PROJECT_ID>") { result in
    ...
}
     
// Get all the temperature devices in the project ordered by
// the temperature (highest temperatures first)
disruptive.getAllDevices(
    projectID   : "<PROJECT_ID>",
    deviceTypes : [.temperature],
    orderBy     : (field: "reported.temperature.value", ascending: false))
{ result in
   ...
}

Parameters

project​ID String

The identifier of the project to get devices from.

query String?

Simple keyword based search. Will be ignored if not set (or nil), which is the default.

device​IDs [String]?

Filters on a list of device identifiers. Will be ignored if not set (or nil), which is the default.

device​Types [Device.​Device​Type]?

Filters on a list of device types. Will be ignored if not set (or nil), which is the default.

label​Filters [String:​ String]?

Filters on a set of labels. Will be ignored if not set (or nil), which is the default.

order​By (field:​ String, ascending:​ Bool)?

Defines a field to order the retrieved devices by. Uses a dot notation format (eg. reported.temperature.value or labels.name). The fields are defined by the JSON structure of a Device. See the REST API documentation for the GET Devices endpoint to get hints for which fields are available. Also provides option to specify ascending or descending order. Will be ignored if not set (or nil), which is the default.

completion @escaping (_ result:​ Result<[Device], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain an array of Devices. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[Device], DisruptiveError>

get​Devices​Page(project​ID:​query:​device​IDs:​device​Types:​label​Filters:​order​By:​page​Size:​page​Token:​completion:​)

public func getDevicesPage(projectID: String, query: String? = nil, deviceIDs: [String]? = nil, deviceTypes: [Device.DeviceType]? = nil, labelFilters: [String: String]? = nil, orderBy: (field: String, ascending: Bool)? = nil, pageSize: Int = 100, pageToken: String?, completion: @escaping (_ result: Result<(nextPageToken: String?, devices: [Device]), DisruptiveError>) -> ())

Gets one page of devices (including emulated devices).

Useful if a lot of devices are expected in the specified project. This function provides better control for when to get devices and how many to get at a time so that devices are only fetch when they are needed. This can also improve performance, at a cost of convenience compared to the getAllDevices function.

Parameters

project​ID String

The identifier of the project to get devices from.

query String?

Simple keyword based search. Will be ignored if not set (or nil), which is the default.

device​IDs [String]?

Filters on a list of device identifiers. Will be ignored if not set (or nil), which is the default.

device​Types [Device.​Device​Type]?

Filters on a list of device types. Will be ignored if not set (or nil), which is the default.

label​Filters [String:​ String]?

Filters on a set of labels. Will be ignored if not set (or nil), which is the default.

order​By (field:​ String, ascending:​ Bool)?

Defines a field to order the retrieved devices by. Uses a dot notation format (eg. reported.temperature.value or labels.name). The fields are defined by the JSON structure of a Device. See the REST API documentation for the GET Devices request to get hints for which fields are available. Also provides option to specify ascending or descending order. Will be ignored if not set (or nil), which is the default.

page​Size Int

The maximum number of devices to get for this page. The maximum page size is 100, which is also the default

page​Token String?

The token of the page to get. For the first page, set this to nil. For subsequent pages, use the nextPageToken received when getting the previous page.

completion @escaping (_ result:​ Result<(next​Page​Token:​ String?, devices:​ [Device]), Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain a tuple with both an array of Devices, as well as the token for the next page. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<(nextPageToken: String?, devices: [Device]), DisruptiveError>

get​Device(project​ID:​device​ID:​completion:​)

public func getDevice(projectID: String? = nil, deviceID: String, completion: @escaping (_ result: Result<Device, DisruptiveError>) -> ())

Gets details for a specific device. This device could be found within a specific project, or if the projectID argument is not specified (or nil), throughout all the project available to the authenticated account.

Parameters

project​ID String?

The identifier of the project to find the device in. If default value (nil) is used, a wildcard character will be used for the projectID that searches through all the project the authenticated account has access to.

device​ID String

The identifier of the device to get details for.

completion @escaping (_ result:​ Result<Device, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the Device. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Device, DisruptiveError>

update​Device​Display​Name(project​ID:​device​ID:​new​Display​Name:​completion:​)

public func updateDeviceDisplayName(projectID: String, deviceID: String, newDisplayName: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Updates the display name of a device to a new value (overwrites it if a display name already exists).

This is a convenience function for batchUpdateDeviceLabels by setting the name label to the new display name.

Parameters

project​ID String

The identifier of the project the device is in.

device​ID String

The identifier of the device to change the display name of.

new​Display​Name String

The new display name to set for the device.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

delete​Device​Label(project​ID:​device​ID:​label​Key:​completion:​)

public func deleteDeviceLabel(projectID: String, deviceID: String, labelKey: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Deletes the specified label for the device. Will return success if the label didn't exist.

This is a convenience function for batchUpdateDeviceLabels.

Parameters

project​ID String

The identifier of the project the device is in.

device​ID String

The identifier of the device to delete a label from.

label​Key String

The key of the label to delete.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

set​Device​Label(project​ID:​device​ID:​label​Key:​label​Value:​completion:​)

public func setDeviceLabel(projectID: String, deviceID: String, labelKey: String, labelValue: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Assigns a value to a label key for a specific device. If the label key doesn't already exists it will be created, otherwise the value for the key is updated. This is in effect an upsert.

This is a convenience function for batchUpdateDeviceLabels.

Parameters

project​ID String

The identifier of the project the device is in.

device​ID String

The identifier of the device to set the label for.

label​Key String

The key of the label.

label​Value String

The new value of the label.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

batch​Update​Device​Labels(project​ID:​device​IDs:​labels​ToSet:​labels​ToRemove:​completion:​)

public func batchUpdateDeviceLabels(projectID: String, deviceIDs: [String], labelsToSet: [String: String], labelsToRemove: [String], completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Performs a batch update to add or remove one or more labels to one or more devices in a project.

Parameters

project​ID String

The identifier of the project the devices are in.

device​IDs [String]

An array of identifiers for the devices to set or remove labels from.

labels​ToSet [String:​ String]

The key-value pairs to set for the device. If the labels already exists they will be updated, otherwise they will be created, effectively doing an upsert. Any labels that already exists on a device, but are not provided here will be left as-is.

labels​ToRemove [String]

An array of label keys to remove from the device.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

move​Devices(device​IDs:​from​Project​ID:​to​Project​ID:​completion:​)

public func moveDevices(deviceIDs: [String], fromProjectID: String, toProjectID: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Moves a list of devices from one project to another. The authenticated account must be an admin in the toProjectID, or an organization admin in which the toProjectID resides.

Parameters

device​IDs [String]

A list of the device identifiers to move from one project to another.

from​Project​ID String

The identifier of the project to move the devices from.

to​Project​ID String

The identifier of the project to move the devices to.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

get​Emulated​Device(project​ID:​device​ID:​completion:​)

public func getEmulatedDevice(projectID: String, deviceID: String, completion: @escaping (_ result: Result<Device, DisruptiveError>) -> ())

Gets details for a specific emulated device within a project.

Parameters

project​ID String

The identifier of the project to find the device in.

device​ID String

The identifier of the emulated device to get details for.

completion @escaping (_ result:​ Result<Device, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the Device. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Device, DisruptiveError>

get​All​Emulated​Devices(project​ID:​completion:​)

public func getAllEmulatedDevices(projectID: String, completion: @escaping (_ result: Result<[Device], DisruptiveError>) -> ())

Gets all the emulated devices in a specific project (without any physical devices).

This will handle pagination automatically and send multiple network requests in the background if necessary. If a lot of emulated devices are expected to be in the project, it might be better to load pages of emulated devices as they're needed using the getEmulatedDevicesPage function instead.

Parameters

project​ID String

The identifier of the project to get emulated devices from.

completion @escaping (_ result:​ Result<[Device], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain an array of Devices. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[Device], DisruptiveError>

get​Emulated​Devices​Page(project​ID:​page​Size:​page​Token:​completion:​)

public func getEmulatedDevicesPage(projectID: String, pageSize: Int = 100, pageToken: String?, completion: @escaping (_ result: Result<(nextPageToken: String?, devices: [Device]), DisruptiveError>) -> ())

Gets one page of emulated devices.

Useful if a lot of emulated devices are expected in the specified project. This function provides better control for when to get emulated devices and how many to get at a time so that emulated devices are only fetch when they are needed. This can also improve performance, at a cost of convenience compared to the getAllEmulatedDevices function.

Parameters

project​ID String

The identifier of the project to get emulated devices from.

page​Size Int

The maximum number of emulated devices to get for this page. The maximum page size is 100, which is also the default

page​Token String?

The token of the page to get. For the first page, set this to nil. For subsequent pages, use the nextPageToken received when getting the previous page.

completion @escaping (_ result:​ Result<(next​Page​Token:​ String?, devices:​ [Device]), Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain a tuple with both an array of Devices, as well as the token for the next page. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<(nextPageToken: String?, devices: [Device]), DisruptiveError>

create​Emulated​Device(project​ID:​device​Type:​display​Name:​labels:​completion:​)

public func createEmulatedDevice(projectID: String, deviceType: Device.DeviceType, displayName: String, labels: [String: String] = [:], completion: @escaping (_ result: Result<Device, DisruptiveError>) -> ())

Creates a new emulated device in a specific project.

Parameters

project​ID String

The identifier of the project to create the emulated device in.

device​Type Device.​Device​Type

The type of device the emulated device should emulate.

display​Name String

The display name of the new emulated device. This will be added as a label with the key name.

labels [String:​ String]

A set of keys and values to use as labels for the emulated device.

completion @escaping (_ result:​ Result<Device, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the newly created Device. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Device, DisruptiveError>

delete​Emulated​Device(project​ID:​device​ID:​completion:​)

public func deleteEmulatedDevice(projectID: String, deviceID: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Deletes an emulated device.

Parameters

project​ID String

The identifier of the project to delete the emulated device from.

device​ID String

The identifier of the emulated device to delete.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

publish​Emulated​Event(project​ID:​device​ID:​event:​completion:​)

public func publishEmulatedEvent<Event: PublishableEvent>(projectID: String, deviceID: String, event: Event, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Publishes a new event to an emulated device.

Any of the event types in Sources/Disruptive/Helpers/EventTypes.swift can be published, although not all event types can be published for every device type. For example, an emulated temperature sensor cannot publish an EthernetStatusEvent. For more details about the different event types, see the Developer Website.

Example:

// Publish a temperature event
publishEmulatedEvent(
    projectID : "<PROJECT_ID>",
    deviceID  : "<DEVICE_ID>",
    event     : TemperatureEvent(value: 10, timestamp: Date())
{ result in
    ...
}

Parameters

project​ID String

The identifier of the project the emulated device is in.

device​ID String

The identifier of the emulated device to publish the event to.

event Event

The event to publish to the emulated device. This can be any event type such as TemperatureEvent, TouchEvent, NetworkStatusEvent, ObjectPresentEvent, etc, as long as it conforms to the PublishableEvent protocol.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

get​Events(project​ID:​device​ID:​start​Date:​end​Date:​event​Types:​completion:​)

public func getEvents(projectID: String, deviceID: String, startDate: Date? = nil, endDate: Date? = nil, eventTypes: [EventType]? = nil, completion: @escaping (_ result: Result<Events, DisruptiveError>) -> ())

Fetches historical data for a specific device from the server. The events are returned with the oldest event at the beginning of the array, and the newest event at the end.

If one or more eventTypes are specified, only those events will be fetched. Otherwise, all the events available for the specified device will be fetched. Note that not all event types are available for all devices.

If startDate or endDate is not specified, it defaults to the last 24 hours.

Parameters

project​ID String

The identifier of the project where the device is.

device​ID String

The identifier of the device to get events from.

start​Date Date?

The timestamp of the first event to fetch. Defaults to 24 hours ago.

end​Date Date?

The timestamp of the last event to fetch. Defaults to now.

event​Types [Event​Type]?

A list of event types to fetch. Defaults to fetching all events for specified device.

completion @escaping (_ result:​ Result<Events, Disruptive​Error>) -> ()

The completion handler that is called when data is returned from the server. This is a Result type where the success case is a list of Events, and the failure case is a DisruptiveError.

result

Result<Events, DisruptiveError>

get​All​Members(organization​ID:​completion:​)

public func getAllMembers(organizationID: String, completion: @escaping (_ result: Result<[Member], DisruptiveError>) -> ())

Gets all the Members for a specific organization.

This will handle pagination automatically and send multiple network requests in the background if necessary. If a lot of Members are expected to be in the organization, it might be better to load pages of Members as they're needed using the getMembersPage function instead.

Parameters

organization​ID String

The identifier of the organization to get Members for.

completion @escaping (_ result:​ Result<[Member], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain an array of Members. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[Member], DisruptiveError>

get​All​Members(project​ID:​completion:​)

public func getAllMembers(projectID: String, completion: @escaping (_ result: Result<[Member], DisruptiveError>) -> ())

Gets all the Members for a specific project.

This will handle pagination automatically and send multiple network requests in the background if necessary. If a lot of Members are expected to be in the project, it might be better to load pages of Members as they're needed using the getMembersPage function instead.

Parameters

project​ID String

The identifier of the project to get Members for.

completion @escaping (_ result:​ Result<[Member], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain an array of Members. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[Member], DisruptiveError>

get​Members​Page(organization​ID:​page​Size:​page​Token:​completion:​)

public func getMembersPage(organizationID: String, pageSize: Int = 100, pageToken: String?, completion: @escaping (_ result: Result<(nextPageToken: String?, members: [Member]), DisruptiveError>) -> ())

Gets one page of Members for a specific organization.

Useful if a lot of Members are expected in the specified organization. This function provides better control for when to get Members and how many to get at a time so that Members are only fetch when they are needed. This can also improve performance, at a cost of convenience compared to the getAllMembers function.

Parameters

organization​ID String

The identifier of the organization to get Members from.

page​Size Int

The maximum number of Members to get for this page. The maximum page size is 100, which is also the default

page​Token String?

The token of the page to get. For the first page, set this to nil. For subsequent pages, use the nextPageToken received when getting the previous page.

completion @escaping (_ result:​ Result<(next​Page​Token:​ String?, members:​ [Member]), Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain a tuple with both an array of Members, as well as the token for the next page. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<(nextPageToken: String?, members: [Member]), DisruptiveError>

get​Members​Page(project​ID:​page​Size:​page​Token:​completion:​)

public func getMembersPage(projectID: String, pageSize: Int = 100, pageToken: String?, completion: @escaping (_ result: Result<(nextPageToken: String?, members: [Member]), DisruptiveError>) -> ())

Gets one page of Members for a specific project.

Useful if a lot of Members are expected in the specified project. This function provides better control for when to get Members and how many to get at a time so that Members are only fetch when they are needed. This can also improve performance, at a cost of convenience compared to the getAllMembers function.

Parameters

project​ID String

The identifier of the project to get Members from.

page​Size Int

The maximum number of Members to get for this page. The maximum page size is 100, which is also the default

page​Token String?

The token of the page to get. For the first page, set this to nil. For subsequent pages, use the nextPageToken received when getting the previous page.

completion @escaping (_ result:​ Result<(next​Page​Token:​ String?, members:​ [Member]), Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain a tuple with both an array of Members, as well as the token for the next page. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<(nextPageToken: String?, members: [Member]), DisruptiveError>

get​Member(organization​ID:​member​ID:​completion:​)

public func getMember(organizationID: String, memberID: String, completion: @escaping (_ result: Result<Member, DisruptiveError>) -> ())

Gets a specific Member within an organization by its identifier.

Parameters

organization​ID String

The identifier of the organization to get the Member from.

member​ID String

The identifier of the Member to get within the specific organization.

completion @escaping (_ result:​ Result<Member, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the Member. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Member, DisruptiveError>

get​Member(project​ID:​member​ID:​completion:​)

public func getMember(projectID: String, memberID: String, completion: @escaping (_ result: Result<Member, DisruptiveError>) -> ())

Gets a specific Member within a project by its identifier.

Parameters

project​ID String

The identifier of the project to get the Member from.

member​ID String

The identifier of the Member to get within the specific project.

completion @escaping (_ result:​ Result<Member, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the Member. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Member, DisruptiveError>

invite​Member(organization​ID:​roles:​email:​completion:​)

public func inviteMember(organizationID: String, roles: [Role.RoleType], email: String, completion: @escaping (_ result: Result<Member, DisruptiveError>) -> ())

Invites a new member to an organization.

If the email belongs to a user that already has an account or a service account, the member will get the status .accepted immediately. Otherwise, the member will get the status .pending, and an invite email will be sent to the user.

Parameters

organization​ID String

The identifier of the organization to invite a member to.

roles [Role.​Role​Type]

The list of roles for the member. Currently, only one role is allowed for a member. The role has to be an organization based role (ie. .organizationAdmin).

email String

The email of the member to invite. Could be the email of a user or a service account.

completion @escaping (_ result:​ Result<Member, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the new Member. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Member, DisruptiveError>

invite​Member(project​ID:​roles:​email:​completion:​)

public func inviteMember(projectID: String, roles: [Role.RoleType], email: String, completion: @escaping (_ result: Result<Member, DisruptiveError>) -> ())

Invites a new member to a project.

If the email belongs to a user that already has an account or a service account, the member will get the status .accepted immediately. Otherwise, the member will get the status .pending, and an invite email will be sent to the user.

Parameters

project​ID String

The identifier of the project to invite a member to.

roles [Role.​Role​Type]

The list of roles for the member. Currently, only one role is allowed for a member. The role has to be a project based role (ie. .projectUser).

email String

The email of the member to invite. Could be the email of a user or a service account.

completion @escaping (_ result:​ Result<Member, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the new Member. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Member, DisruptiveError>

update​Member(project​ID:​member​ID:​roles:​completion:​)

public func updateMember(projectID: String, memberID: String, roles: [Role.RoleType], completion: @escaping (_ result: Result<Member, DisruptiveError>) -> ())

Updates the Member of a project.

Parameters

project​ID String

The identifier of the project the Member is in.

member​ID String

The identifier of the Member to update.

roles [Role.​Role​Type]

The new role to assign to the Member. Must be a role appropriate a project (ie. .projectUser).

completion @escaping (_ result:​ Result<Member, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the updated Member. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Member, DisruptiveError>

delete​Member(organization​ID:​member​ID:​completion:​)

public func deleteMember(organizationID: String, memberID: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Deletes a member from an organization.

Parameters

organization​ID String

The identifier of the organization the member is a part of.

member​ID String

The identifier of the member to delete.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

delete​Member(project​ID:​member​ID:​completion:​)

public func deleteMember(projectID: String, memberID: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Deletes a member from a project.

Parameters

project​ID String

The identifier of the project the member is a part of.

member​ID String

The identifier of the member to delete.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

get​Member​Invite​URL(organization​ID:​member​ID:​completion:​)

public func getMemberInviteURL(organizationID: String, memberID: String, completion: @escaping (_ result: Result<URL, DisruptiveError>) -> ())

Retrieves the invite URL that allows a new user to set up their account in an organization.

  • The accountType of the member must be .user.

  • The status of the member must be .pending.

Parameters

organization​ID String

The identifier of the organization the member is a part of.

member​ID String

The identifier of the member to get an invite URL for.

completion @escaping (_ result:​ Result<URL, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned with the invite URL as a URL, otherwise a DisruptiveError is returned in the .failure case.

result

Result<URL, DisruptiveError>

get​Member​Invite​URL(project​ID:​member​ID:​completion:​)

public func getMemberInviteURL(projectID: String, memberID: String, completion: @escaping (_ result: Result<URL, DisruptiveError>) -> ())

Retrieves the invite URL that allows a new user to set up their account in a project.

  • The accountType of the member must be .user.

  • The status of the member must be .pending.

Parameters

project​ID String

The identifier of the project the member is a part of.

member​ID String

The identifier of the member to get an invite URL for.

completion @escaping (_ result:​ Result<URL, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned with the invite URL as a URL, otherwise a DisruptiveError is returned in the .failure case.

result

Result<URL, DisruptiveError>

get​All​Organizations(completion:​)

public func getAllOrganizations(completion: @escaping (_ result: Result<[Organization], DisruptiveError>) -> ())

Gets all the organizations available to the authenticated account.

This will handle pagination automatically and send multiple network requests in the background if necessary. If a lot of organizations are expected to be available, it might be better to load pages of organizations as they're needed using the getOrganizationsPage function instead.

Parameters

completion @escaping (_ result:​ Result<[Organization], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain an array of Organizations. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[Organization], DisruptiveError>

get​Organizations​Page(page​Size:​page​Token:​completion:​)

public func getOrganizationsPage(pageSize: Int = 100, pageToken: String?, completion: @escaping (_ result: Result<(nextPageToken: String?, organizations: [Organization]), DisruptiveError>) -> ())

Gets one page of organizations available to the authenticated account.

Useful if a lot of organizations are expected to be available. This function provides better control for when to get organizations and how many to get at a time so that organizations are only fetch when they are needed. This can also improve performance, at a cost of convenience compared to the getAllOrganizations function.

Parameters

page​Size Int

The maximum number of organizations to get for this page. The maximum page size is 100, which is also the default

page​Token String?

The token of the page to get. For the first page, set this to nil. For subsequent pages, use the nextPageToken received when getting the previous page.

completion @escaping (_ result:​ Result<(next​Page​Token:​ String?, organizations:​ [Organization]), Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain a tuple with both an array of Organizations, as well as the token for the next page. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<(nextPageToken: String?, organizations: [Organization]), DisruptiveError>

get​Organization(organization​ID:​completion:​)

public func getOrganization(organizationID: String, completion: @escaping (_ result: Result<Organization, DisruptiveError>) -> ())

Gets a single organization based on an organization identifier.

Parameters

organization​ID String

The identifier of the organization to get.

completion @escaping (_ result:​ Result<Organization, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the Organization. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Organization, DisruptiveError>

get​Permissions(organization​ID:​completion:​)

public func getPermissions(organizationID: String, completion: @escaping (_ result: Result<[Permission], DisruptiveError>) -> ())

Gets all the permissions the currently logged in user has for the given organization.

Parameters

organization​ID String

The identifier of the organization to get the permissions for.

completion @escaping (_ result:​ Result<[Permission], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned containing an array of all the available permissions. Otherwise a DisruptiveError is returned in the .failure case.

result

Result<[Permission], DisruptiveError>

get​Permissions(project​ID:​completion:​)

public func getPermissions(projectID: String, completion: @escaping (_ result: Result<[Permission], DisruptiveError>) -> ())

Gets all the permissions the currently logged in user has for the given project.

Parameters

project​ID String

The identifier of the project to get the permissions for.

completion @escaping (_ result:​ Result<[Permission], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned containing an array of all the available permissions. Otherwise a DisruptiveError is returned in the .failure case.

result

Result<[Permission], DisruptiveError>

get​All​Projects(organization​ID:​query:​completion:​)

public func getAllProjects(organizationID: String? = nil, query: String? = nil, completion: @escaping (_ result: Result<[Project], DisruptiveError>) -> ())

Gets a list of all projects that matches the query/organizationID.

If an organizationID is specified, only projects within this organization are fetched. Otherwise, all the projects the authenticated account has access to is returned. A query string can also be used for simple keyword based search.

This will handle pagination automatically and send multiple network requests in the background if necessary. If a lot of projects are expected to be available, it might be better to load pages of projects as they're needed using the getProjectsPage function instead.

Parameters

organization​ID String?

Optional parameter. The identifier of the organization to get projects from. If not specified (or nil), will fetch all the project the authenticated account has access to.

query String?

Optional parameter. Simple keyword based search. If not specified (or nil), all projects will be returned.

completion @escaping (_ result:​ Result<[Project], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain an array of Projects. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[Project], DisruptiveError>

get​Projects​Page(organization​ID:​query:​page​Size:​page​Token:​completion:​)

public func getProjectsPage(organizationID: String? = nil, query: String? = nil, pageSize: Int = 100, pageToken: String?, completion: @escaping (_ result: Result<(nextPageToken: String?, projects: [Project]), DisruptiveError>) -> ())

Gets one page of projects that matches the query/organizationID

If an organizationID is specified, only projects within this organization are fetched. Otherwise, one page of the projects the authenticated account has access to is returned. A query string can also be used for simple keyword based search.

Useful if a lot of projects are expected to be available. This function provides better control for when to get projects and how many to get at a time so that projects are only fetch when they are needed. This can also improve performance, at a cost of convenience compared to the getAllProjects function.

Parameters

organization​ID String?

Optional parameter. The identifier of the organization to get projects from. If not specified (or nil), will fetch projects the authenticated account has access to from all organizations.

query String?

Optional parameter. Simple keyword based search. If not specified (or nil), any projects will be returned.

page​Size Int

The maximum number of projects to get for this page. The maximum page size is 100, which is also the default

page​Token String?

The token of the page to get. For the first page, set this to nil. For subsequent pages, use the nextPageToken received when getting the previous page.

completion @escaping (_ result:​ Result<(next​Page​Token:​ String?, projects:​ [Project]), Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain a tuple with both an array of Projects, as well as the token for the next page. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<(nextPageToken: String?, projects: [Project]), DisruptiveError>

get​Project(project​ID:​completion:​)

public func getProject(projectID: String, completion: @escaping (_ result: Result<Project, DisruptiveError>) -> ())

Gets details for a specific project.

Parameters

project​ID String

The identifier of the project to get details for.

completion @escaping (_ result:​ Result<Project, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the Project. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Project, DisruptiveError>

create​Project(organization​ID:​display​Name:​completion:​)

public func createProject(organizationID: String, displayName: String, completion: @escaping (_ result: Result<Project, DisruptiveError>) -> ())

Creates a new project in a specific organization. The newly created project will be returned (including it's identifier, etc) if successful.

Parameters

organization​ID String

The identifier of the organization to create the project in.

display​Name String

The display name of the new project.

completion @escaping (_ result:​ Result<Project, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the Project. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Project, DisruptiveError>

delete​Project(project​ID:​completion:​)

public func deleteProject(projectID: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Deletes a project. Deleting a project can only be done if it has no devices, Service Accounts, or Data Connectors in it. Otherwise, an error will be returned.

Parameters

project​ID String

The identifier of the project to delete.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

update​Project​Display​Name(project​ID:​new​Display​Name:​completion:​)

public func updateProjectDisplayName(projectID: String, newDisplayName: String, completion: @escaping (_ result: Result<Project, DisruptiveError>) -> ())

Updates the display name of a project, and returns the new project (with the updated name) if successful.

Parameters

project​ID String

The identifier of the project to update the display name of.

new​Display​Name String

The new display name to set for the project.

completion @escaping (_ result:​ Result<Project, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the Project with the updated display name. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Project, DisruptiveError>

get​Roles(completion:​)

public func getRoles(completion: @escaping (_ result: Result<[Role], DisruptiveError>) -> ())

Get a list of all the available roles that can be assigned to a member of a project or an organization.

Parameters

completion @escaping (_ result:​ Result<[Role], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the array of Roles. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[Role], DisruptiveError>

get​Role(role​Type:​completion:​)

public func getRole(roleType: Role.RoleType, completion: @escaping (_ result: Result<Role, DisruptiveError>) -> ())

Get the details for a specific role.

Parameters

role​Type Role.​Role​Type

The type of role to get.

completion @escaping (_ result:​ Result<Role, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the Role. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<Role, DisruptiveError>

get​All​Service​Accounts(project​ID:​completion:​)

public func getAllServiceAccounts(projectID: String, completion: @escaping (_ result: Result<[ServiceAccount], DisruptiveError>) -> ())

Gets all the Service Accounts that are available in a specific project.

This will handle pagination automatically and send multiple network requests in the background if necessary. If a lot of Service Accounts are expected to be in the project, it might be better to load pages of Service Accounts as they're needed using the getServiceAccountsPage function instead.

Parameters

project​ID String

The identifier of the project to get Service Accounts from.

completion @escaping (_ result:​ Result<[Service​Account], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain an array of ServiceAccounts. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[ServiceAccount], DisruptiveError>

get​Service​Accounts​Page(project​ID:​page​Size:​page​Token:​completion:​)

public func getServiceAccountsPage(projectID: String, pageSize: Int = 100, pageToken: String?, completion: @escaping (_ result: Result<(nextPageToken: String?, serviceAccounts: [ServiceAccount]), DisruptiveError>) -> ())

Gets one page of Service Accounts.

Useful if a lot of Service Accounts are expected in the specified project. This function provides better control for when to get Service Accounts and how many to get at a time so that Service Accounts are only fetch when they are needed. This can also improve performance, at a cost of convenience compared to the getAllServiceAccounts function.

Parameters

project​ID String

The identifier of the project to get Service Accounts from.

page​Size Int

The maximum number of Service Accounts to get for this page. The maximum page size is 100, which is also the default

page​Token String?

The token of the page to get. For the first page, set this to nil. For subsequent pages, use the nextPageToken received when getting the previous page.

completion @escaping (_ result:​ Result<(next​Page​Token:​ String?, service​Accounts:​ [Service​Account]), Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain a tuple with both an array of ServiceAccounts, as well as the token for the next page. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<(nextPageToken: String?, serviceAccounts: [ServiceAccount]), DisruptiveError>

get​Service​Account(project​ID:​service​Account​ID:​completion:​)

public func getServiceAccount(projectID: String, serviceAccountID: String, completion: @escaping (_ result: Result<ServiceAccount, DisruptiveError>) -> ())

Gets a specific Service Account within a project by its identifier.

Parameters

project​ID String

The identifier of the project to get the Service Account from.

service​Account​ID String

The identifier of the Service Account to get within the specified project.

completion @escaping (_ result:​ Result<Service​Account, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the ServiceAccount. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<ServiceAccount, DisruptiveError>

create​Service​Account(project​ID:​display​Name:​basic​Auth​Enabled:​completion:​)

public func createServiceAccount(projectID: String, displayName: String, basicAuthEnabled: Bool = false, completion: @escaping (_ result: Result<ServiceAccount, DisruptiveError>) -> ())

Creates a new Service Account within a specific project.

NOTE: This Service Account will by default not have access to any resources. In order to allow the Service Account to send API requests, add it as a Member to a project or an organization.

Parameters

project​ID String

The identifier of the project to create the Service Account in.

display​Name String

The display name to give the Service Account.

basic​Auth​Enabled Bool

Whether or not the Service Account should be able to be authenticated using HTTP basic auth. This is not recommended in a production environment. The default value is false.

completion @escaping (_ result:​ Result<Service​Account, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the ServiceAccount (along with its generated identifier). If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<ServiceAccount, DisruptiveError>

update​Service​Account(project​ID:​service​Account​ID:​display​Name:​basic​Auth​Enabled:​completion:​)

public func updateServiceAccount(projectID: String, serviceAccountID: String, displayName: String? = nil, basicAuthEnabled: Bool? = nil, completion: @escaping (_ result: Result<ServiceAccount, DisruptiveError>) -> ())

Updates parameters of a specific Service Account. Only the parameters that are set will be updated, and the remaining will be left unchanged.

Examples:

// Enable basic auth
disruptive.updateServiceAccount(
    projectID        : "<PROJECT_ID>",
    serviceAccountID : "<SERVICE_ACCOUNT_ID>",
    basicAuthEnabled : true)
{ result in
    ...
}
     
// Change the display name
disruptive.updateServiceAccount(
    projectID        : "<PROJECT_ID>",
    serviceAccountID : "<SERVICE_ACCOUNT_ID>",
    displayName      : "New Display Name")
{ result in
    ...
}

Parameters

project​ID String

The identifier of the project the Service Account to update is in.

service​Account​ID String

The identifier of the Service Account to update.

display​Name String?

The new display name to use for the Service Account. Will be ignored if not set (or nil). Defaults to nil.

basic​Auth​Enabled Bool?

Enables or disables HTTP basic auth for a Service Account. It is recommended to set this to false in a production environment. Will be ignored if not set (or nil). Defaults to nil.

completion @escaping (_ result:​ Result<Service​Account, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the updated ServiceAccount. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<ServiceAccount, DisruptiveError>

delete​Service​Account(project​ID:​service​Account​ID:​completion:​)

public func deleteServiceAccount(projectID: String, serviceAccountID: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Deletes a Service Account.

Parameters

project​ID String

The identifier of the project to delete the Service Account from.

service​Account​ID String

The identifier of the Service Account to delete.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

get​All​Service​Account​Keys(project​ID:​service​Account​ID:​completion:​)

public func getAllServiceAccountKeys(projectID: String, serviceAccountID: String, completion: @escaping (_ result: Result<[ServiceAccount.Key], DisruptiveError>) -> ())

Gets all the keys for a specific Service Account.

This will handle pagination automatically and send multiple network requests in the background if necessary. If a lot of keys are expected to be available for the Service Account, it might be better to load pages of keys as they're needed using the getServiceAccountKeysPage function instead.

Parameters

project​ID String

The identifier of the project the Service Account is in.

service​Account​ID String

The identifier of the Service Account to get keys for.

completion @escaping (_ result:​ Result<[Service​Account.​Key], Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain an array of ServiceAccount.Keys. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<[ServiceAccount.Key], DisruptiveError>

get​Service​Account​Keys​Page(project​ID:​service​Account​ID:​page​Size:​page​Token:​completion:​)

public func getServiceAccountKeysPage(projectID: String, serviceAccountID: String, pageSize: Int = 100, pageToken: String?, completion: @escaping (_ result: Result<(nextPageToken: String?, keys: [ServiceAccount.Key]), DisruptiveError>) -> ())

Gets one page of keys for a specific Service Account.

Useful if a lot of keys are expected to be available for this Service Account. This function provides better control for when to get keys and how many to get at a time so that keys are only fetch when they are needed. This can also improve performance, at a cost of convenience compared to the getAllServiceAccountKeys function.

Parameters

project​ID String

The identifier of the project the Service Account is in.

service​Account​ID String

The identifier of the Service Account to get keys for.

page​Size Int

The maximum number of keys to get for this page. The maximum page size is 100, which is also the default

page​Token String?

The token of the page to get. For the first page, set this to nil. For subsequent pages, use the nextPageToken received when getting the previous page.

completion @escaping (_ result:​ Result<(next​Page​Token:​ String?, keys:​ [Service​Account.​Key]), Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain a tuple with both an array of ServiceAccount.Keys, as well as the token for the next page. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<(nextPageToken: String?, keys: [ServiceAccount.Key]), DisruptiveError>

get​Service​Account​Key(project​ID:​service​Account​ID:​key​ID:​completion:​)

public func getServiceAccountKey(projectID: String, serviceAccountID: String, keyID: String, completion: @escaping (_ result: Result<ServiceAccount.Key, DisruptiveError>) -> ())

Gets a single key for a specific Service Account.

Parameters

project​ID String

The identifier of the project the Service Account is in.

service​Account​ID String

The identifier of the Service Account to get a key for.

key​ID String

The identifier of the key to get.

completion @escaping (_ result:​ Result<Service​Account.​Key, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the ServiceAccount.Key. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<ServiceAccount.Key, DisruptiveError>

create​Service​Account​Key(project​ID:​service​Account​ID:​completion:​)

public func createServiceAccountKey(projectID: String, serviceAccountID: String, completion: @escaping (_ result: Result<ServiceAccount.KeySecret, DisruptiveError>) -> ())

Creates a new key for a Service Account, and gets both the key and the corresponding secret in return.

Note a couple of things:

  • The secret that is returned can not be retrieved later, so make sure to take a note of it.

  • A Service Account can have a maximum of 10 keys.

Parameters

project​ID String

The identifier of the project the Service Account is in.

service​Account​ID String

The identifier of the Service Account to create a new key for.

completion @escaping (_ result:​ Result<Service​Account.​Key​Secret, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success case of the result will contain the ServiceAccount.KeySecret. If a failure occurred, the .failure case will contain a DisruptiveError.

result

Result<ServiceAccount.KeySecret, DisruptiveError>

delete​Service​Account​Key(project​ID:​service​Account​ID:​key​ID:​completion:​)

public func deleteServiceAccountKey(projectID: String, serviceAccountID: String, keyID: String, completion: @escaping (_ result: Result<Void, DisruptiveError>) -> ())

Deletes a key for a Service Account.

This will prevent the Service Account from being able to authenticate using the deleted key.

Parameters

project​ID String

The identifier of the project the Service Account is in.

service​Account​ID String

The identifier of the Service Account to delete a key for.

key​ID String

The identifier of the key to delete.

completion @escaping (_ result:​ Result<Void, Disruptive​Error>) -> ()

The completion handler to be called when a response is received from the server. If successful, the .success result case is returned, otherwise a DisruptiveError is returned in the .failure case.

result

Result<Void, DisruptiveError>

subscribe​ToDevices(project​ID:​device​IDs:​device​Types:​label​Filters:​event​Types:​)

public func subscribeToDevices(projectID: String, deviceIDs: [String]? = nil, deviceTypes: [Device.DeviceType]? = nil, labelFilters: [String]? = nil, eventTypes: [EventType]? = nil) -> DeviceEventStream?

Sets up a device stream to one or more devices in a specific project using server-sent-events. By default, all events for all the devices in the specified project will be subscribed to. The various arguments are ways to limit which devices and event types gets subscribed to.

Example:

let stream = disruptive.subscribeToDevices(projectID: "<PROJECT_ID>")
stream?.onTemperature = { deviceID, tempEvent in
   print("Got \(tempEvent) from \(deviceID)")
}

Parameters

project​ID String

The identifier of the project that contains the device(s).

device​IDs [String]?

An array of device identifiers to subscribe to. If not specified (or nil), all the devices in the project will be subscribed to.

device​Types [Device.​Device​Type]?

An array of device types to subscribe to. This is useful if nil is specified for the deviceIDs argument.

label​Filters [String]?

An array of label filter expressions that filters the set of devices for the results. Each expression takes the form labelKey=labelValue.

event​Types [Event​Type]?

An array of event types to subscribe to.

Returns

A DeviceEventStream device stream object with callbacks for each type of event. For example, set a closure on the onNetworkStatus property to receive an event each time a device sends out a heart beat.

subscribe​ToDevice(project​ID:​device​ID:​event​Types:​)

public func subscribeToDevice(projectID: String, deviceID: String, eventTypes: [EventType]? = nil) -> DeviceEventStream?

Convenience function to subscribe to just a single device. See subscribeToDevices for more details.

Parameters

project​ID String

The identifier of the project the device is currently in.

device​ID String

The identifier of the device to subscribe to.

event​Types [Event​Type]?

Optional parameter to specify which event types to subscribe to. If this is omitted, all the available event types for this device will be received.