Endpoints

Access Token

Manage personal access tokens to authenticate with drogue cloud.

GET /api/tokens/v1alpha1

List access tokens for this user.

Responses

Code Description

200

All access tokens for this user.

application/json

List of ResponseApiTokensV1alpha1Get200ApplicationJsonItems

POST /api/tokens/v1alpha1

Create a new access tokens for this user.

Parameters

Name Location Type Description

description

query

string

A description to attach to the token entry.

Responses

Code Description

200

A new access token was created.

application/json

ResponseApiTokensV1alpha1Post200ApplicationJson

DELETE /api/tokens/v1alpha1/{prefix}

Delete an access token by prefix.

Parameters

Name Location Type Description
prefix*

path

string

The prefix of the access token to delete.

Responses

Code Description

204

Successfully deleted the token.

If the access token didn't exist, still 204 will be returned.

Registry

Manage application and devices in the registry.

GET /api/registry/v1alpha1/apps

Return all the applications the user has access to

Parameters

Name Location Type Description

labels

query

List of string

Labels selectors.

Labels are arbitrary <key>:<value> pairs that can be associated with a resource. A selector matches labels values using equality, inequality and filtering. It can check the existence of a label key, ignoring the value.
To summarize, there are 6 available operations and their associated symbol :

  • equality: =
  • inequality: !=
  • filtering: in
  • negative-filetering: notin
  • existence: <key>
  • non-existence: !<key>

For example :
zone=europe will match a label where the value for key zone is equal to europe.
zone!=europe will match all the labels where the value for key zone is not equal to europe.
country in (france, germany) will match all the labels where the value for key country is equal to france or germany.
country notin (spain, italy) will match all the labels where the value for key country is not equal to spain or italy.
power will match all the labels where the key power exist, regardless of the value.
!power will match all the labels where the key power do not exist.

Multiple selectors can be submited, separated with a coma. A coma implies a AND operation between selectors.
This is modeled after the kubernetes labels.

limit

query

integer

The maximum number of elements to return.

offset

query

integer

The number of elements to skip when returning. The elements will by ordered "by name".

Responses

Code Description

200

A list of applications.

401

Unauthorized.

POST /api/registry/v1alpha1/apps

create new application.

Request

The data section of the application to add

Content Type Description

application/json

App

Responses

Code Description

201

If the application is created

409

If the application id is already used.

GET /api/registry/v1alpha1/apps/{appId}

Return application details.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

Responses

Code Description

200

The data of the application

application/json

App

404

If the requested application does not exist or if the user has no access to it.

PUT /api/registry/v1alpha1/apps/{appId}

update existing app

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

Request

The data of the application to update

Content Type Description

application/json

App

Responses

Code Description

204

If the application is updated

404

If the requested application does not exist or if the user has no access to it.

DELETE /api/registry/v1alpha1/apps/{appId}

Delete existing application

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

uid

query

string

The expected UID of the entry, for optimistic locking.

resourceVersion

query

string

The resource version of the existing data, for optimistic locking.

Responses

Code Description

204

If the application is deleted

404

If the requested application does not exist or if the user has not access to it.

PATCH /api/registry/v1alpha1/apps/{appId}

FUTURE USE: Patch existing app

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

uid

query

string

The expected UID of the entry, for optimistic locking.

resourceVersion

query

string

The resource version of the existing data, for optimistic locking.

Request

The JSON patch to apply

Content Type Description

application/json

#/components/schema/Patch

Responses

Code Description

204

If the app is updated

404

If requested apps do not exits or if the user has not access to them.

GET /api/registry/v1alpha1/apps/{appId}/devices

Return all the devices of the application.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

labels

query

List of string

Labels selectors.

Labels are arbitrary <key>:<value> pairs that can be associated with a resource. A selector matches labels values using equality, inequality and filtering. It can check the existence of a label key, ignoring the value.
To summarize, there are 6 available operations and their associated symbol :

  • equality: =
  • inequality: !=
  • filtering: in
  • negative-filetering: notin
  • existence: <key>
  • non-existence: !<key>

For example :
zone=europe will match a label where the value for key zone is equal to europe.
zone!=europe will match all the labels where the value for key zone is not equal to europe.
country in (france, germany) will match all the labels where the value for key country is equal to france or germany.
country notin (spain, italy) will match all the labels where the value for key country is not equal to spain or italy.
power will match all the labels where the key power exist, regardless of the value.
!power will match all the labels where the key power do not exist.

Multiple selectors can be submited, separated with a coma. A coma implies a AND operation between selectors.
This is modeled after the kubernetes labels.

limit

query

integer

The maximum number of elements to return.

offset

query

integer

The number of elements to skip when returning. The elements will by ordered "by name".

Responses

Code Description

200

A list of devices.

401

Unauthorized.

POST /api/registry/v1alpha1/apps/{appId}/devices

Create a new device.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

Request

The device object to add.

Content Type Description

application/json

Device

Responses

Code Description

201

If the device is created.

409

If the device id is already used.

GET /api/registry/v1alpha1/apps/{appId}/devices/{deviceId}

Return device details.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.
deviceId*

path

string

The device ID.

Responses

Code Description

200

The data of the device

application/json

Device

404

If requested device does not exist or if the user has no access to it.

PUT /api/registry/v1alpha1/apps/{appId}/devices/{deviceId}

update existing device

Parameters

Name Location Type Description
appId*

path

string

The Application ID.
deviceId*

path

string

The device ID.

Request

The data object of the device to update

Content Type Description

application/json

Device

Responses

Code Description

204

If the device is updated

404

If requested device does not exist or if the user has no access to it.

DELETE /api/registry/v1alpha1/apps/{appId}/devices/{deviceId}

Delete existing device

Parameters

Name Location Type Description
appId*

path

string

The Application ID.
deviceId*

path

string

The device ID.

uid

query

string

The expected UID of the entry, for optimistic locking.

resourceVersion

query

string

The resource version of the existing data, for optimistic locking.

Responses

Code Description

204

If the device is deleted

404

If requested device does not exist or if the user has no access to it.

PATCH /api/registry/v1alpha1/apps/{appId}/devices/{deviceId}

FUTURE USE: Patch existing device

Parameters

Name Location Type Description
appId*

path

string

The Application ID.
deviceId*

path

string

The device ID.

uid

query

string

The expected UID of the entry, for optimistic locking.

resourceVersion

query

string

The resource version of the existing data, for optimistic locking.

Request

The JSON patch to apply

Content Type Description

application/json

Patch

Responses

Code Description

204

If the device is updated

404

If requested device does not exist or if the user has no access to it.

Application administration

Manage applications members and authorizations.

GET /api/admin/v1alpha1/apps/{appId}/transfer-ownership

Retrieve state of the application transfer

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

Responses

Code Description

200

An transfer is pending for this application.

application/json

ResponseApiAdminV1alpha1AppsAppIdTransferOwnershipGet200ApplicationJson

204

There is no current pending transfer for this application.

404

The application does not exist, or the user does not have access to the information.

PUT /api/admin/v1alpha1/apps/{appId}/transfer-ownership

Initiate the process to transfer the ownership.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

Request

Content Type Description

application/json

RequestBodyApiAdminV1alpha1AppsAppIdTransferOwnershipPutApplicationJson

Responses

Code Description

202

Transfer process is initiated.

404

If the requested application does not exist or if the user has no access to it.

DELETE /api/admin/v1alpha1/apps/{appId}/transfer-ownership

Cancel an ownership transfer.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

Responses

Code Description

204

The transfer was successfully canceled.

404

The user has no access to the resource.

This is also the case, when the transfer was already completed successfully.

PUT /api/admin/v1alpha1/apps/{appId}/accept-ownership

Accept an application as new owner.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

Responses

Code Description

204

Ownership is transfered.

404

If the requested application does not exist or if the user has no access to it.

GET /api/admin/v1alpha1/apps/{appId}/members

Get curretn application members.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

Responses

Code Description

200

The list of members for this application.

application/json

ApplicationMembers

404

If the requested application does not exist or if the user has no access to it.

PUT /api/admin/v1alpha1/apps/{appId}/members

Update existing application member list.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.

Request

The new application member list.

Content Type Description

application/json

ApplicationMembers

Responses

Code Description

204

The application's member list was updated.

400

The payload format was invalid.

404

If requested application does not exist or if the user has no access to it.

409

In case a resource version was provided in the update, but it did not match the current version of the resource.

User administration

Manage users

GET /api/admin/v1alpha1/user/whoami

Get information about the current user.

Responses

Code Description

200

Information about the current user.

application/json

ResponseApiAdminV1alpha1UserWhoamiGet200ApplicationJson

403

In case the user is not logged in.

Command & Control

Send commands to devices and check the results.

POST /api/command/v1alpha1/apps/{appId}/devices/{deviceId}

Send one way commands to devices.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.
deviceId*

path

string

The device ID.
command*

query

CommandName

Command to execute

Request

Optional payload for the command

Content Type Description

application/json

CommandObject

Responses

Code Description

202

The command was accepted for processing, but there is no further information if or when the command will be sent to the device.

As commands are considered short-lived, command which cannot be sent in the near future will get discarded.

401

Invalid authentication.

404

Device or application not found.

406

Device is not found or disabled.

GET /api/command/v1alpha1/inbox/apps/{appId}/devices/{deviceId}

Explicitly wait for commands

Parameters

Name Location Type Description
appId*

path

string

The Application ID.
deviceId*

path

string

The device ID.

timeout

query

Timeout

Wait for commands for specified amount of time in seconds.

Responses

Code Description

200

The response contain a command.

application/json

CommandObject

Headers

Command

Command to be executed

Map of objects
Request

Request identifier used to correlate response with.

string

404

No command available.

POST /api/command/v1alpha1/outbox/apps/{appId}/devices/{deviceId}

Send a command result.

Parameters

Name Location Type Description
appId*

path

string

The Application ID.
deviceId*

path

string

The device ID.

request

query

string

Request identifier used to correlate response with.
status*

query

string

Status code of commands execution.

Request

Optional payload for the command response

Content Type Description

application/json

Map of objects

Responses

Code Description

200

Command result saved.

System information

Get information of the system.

GET /.well-known/drogue-version

Get version

Responses

Code Description

200

Version response

application/json

ResponseWellKnownDrogueVersionGet200ApplicationJson

GET /.well-known/drogue-endpoints

Get publicly known endpoints

Responses

Code Description

200

Public endpoints

application/json

Map of objects