Installations

Location /api/apps/{appID}/installations
Collection of installations of the current application. An installation in Kii Cloud represents an installation of the application in a concrete device.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

POST

/api/apps/{appID}/installations

Description

Register a new installation.

The owner of the installation is determined by the access token used for requesting the installation:

  • If a user token is used, the corresponding user becomes the owner of the installation. Please do not fill in the fields "userID" and "thingID" in the request.
  • If a thing token is used, the corresponding thing becomes the owner of the installation. Please do not fill in the fields "userID" and "thingID" in the request.
  • If an app administrator token is used, you need to specify the owner of the installation explicitly by filling either the "userID" or "thingID" field in the request.

The "deviceType" specifies the type of the installation. The available types are ANDROID, IOS, JPUSH, and MQTT.

  • If you are installing ANDROID, IOS, or JPUSH, you need to provide the "installationRegistrationID". A pair of the "deviceType" and "installationRegistrationID" constitutes a unique key. If you call this method with the already-existing pair of the "deviceType" and "installationRegistrationID", the owner of the installation will be updated on the basis of the access token. Note that the method will not fail if the access token points to the same owner and thus makes no change in the installation owner.
  • If you are installing MQTT, you do not need to provide the "installationRegistrationID". The server will generate the ID and return it in the response. If the owner already has an MQTT installation, no new installation will be registered. The server will return the "installationID" and "installationRegistrationID" of the existing installation.

Security

Can be performed with an app administrator, user, and thing token.

Content-Type application/vnd.kii.InstallationCreationRequest+json

All the required data for creating the installation.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
Params
Name Required? Type Description
installationRegistrationID string The registrationID that indentifies the installation in the external service.
deviceType Yes string The installation type. The value can be "ANDROID", "IOS", "JPUSH", or "MQTT".
userID string The userID of the installation owner.
thingID string The thingID of the installation owner.
development boolean The flag that indicates if the installation is for the development or production environment.
Sample Request 
{
  "installationRegistrationID": "[string]",
  "deviceType": "[string]",
  "userID": "[string]",
  "thingID": "[string]",
  "development": "[boolean]"
}
Responses
201

Content-Type application/vnd.kii.InstallationCreationResponse+json

The installation has been registered successfully.
Headers
Name Type Description
Location string The URI to the registered installation
Contents
Name Type Description
InstallationID string The ID of the installation in Kii Cloud.
installationRegistrationID string The registrationID that indentifies the installation in the external service. This ID is only provided for the "MQTT" installation.
404

Content-Type application/vnd.kii.UserNotFoundException+json

The owner of the installation was not found.
Contents
Name Type Description
errorCode string Error code "USER_NOT_FOUND".
message string The error message.
field string The field used for searching the user. This can be the userID or address field.
value string The field value used for searching the user.
appID string The ID of the application.
400

Content-Type application/vnd.kii.ValidationException+json

Happens when:
  • A mandatory field was not provided in the request
  • "installationRegistrationID" was provided for an "MQTT" installation
  • "userID" or "thingID" were provided when using a user or thing token
  • Both "userID" and "thingID" were provided when using an app admin or anonymous token
Contents
Name Type Description
errorCode string Error code "INVALID_INPUT_DATA".
message string The error message.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to register the installation.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

GET

/api/apps/{appID}/installations

Description

Retrieve the installations.

If either "userID" or "thingID" is specified, the installations owned by the corresponding user or thing will be retrieved. If neither of them is specified, all installations registered in the application will be retrieved.

Security

  • Retrieving the installations of a certain owner can be performed by the owner himself and the administrator.
  • Retrieving all installations in the application can be performed only by the administrator.

Content-Type application/json

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
Params
Name Required? Type Description
userID No string The userID of the installation owner.
thingID No string The thingID of the installation owner.
paginationKey No string The pagination key for querying the next page of installations.
Responses
200

Content-Type application/vnd.kii.InstallationsRetrievalResponse+json

The installations of the user/thing have been retrieved successfully.
Contents
Name Type Description
installations InstallationRetrievalResponse
installationID string The ID of the installation
installationRegistrationID string The ID of the registration that identifies the device externally.
deviceType string The type of the installation.
userID string The userID of the installation owner.
thingID string The thingID of the installation owner.
development boolean The flag that indicates if the installation is for development or production environment.
paginationKey string The paginationKey for getting the next page of installations (if available).
400

Content-Type application/vnd.kii.ValidationException+json

Both "userID" and "thingID" were provided.
Contents
Name Type Description
errorCode string Error code "INVALID_INPUT_DATA".
message string The error message.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to retrieve the installations.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).