## # Copyright © 2019 contains code contributed by Orange SA, authors: Denis Barbaron - Licensed under the Apache license 2.0 ## swagger: "2.0" info: version: "2.4.0" title: Smartphone Test Farm description: Control and manages real Smartphone devices from browser and restful apis license: name: Apache-2.0 url: http://www.apache.org/licenses/LICENSE-2.0 contact: name: STF Team email: contact@openstf.io url: http://openstf.io/ basePath: /api/v1 schemes: - http - https consumes: - application/json - application/octet-stream produces: - application/json tags: - name: user description: User Operations - name: users description: Users Operations - name: devices description: Device Operations - name: groups description: Groups Operations - name: admin description: Privileged Operations paths: /groups: x-swagger-router-controller: groups get: summary: Gets groups description: Returns the groups to which you belong operationId: getGroups tags: - groups parameters: - name: fields in: query description: Comma-seperated list of fields; only listed fields will be returned in response required: false type: string - name: owner in: query description: Selects the groups for which you are the owner (true) or a simple member (false); note that by not providing this parameter, it means all groups to which you belong are selected required: false type: boolean responses: "200": description: Groups information schema: $ref: "#/definitions/GroupListResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes groups description: Removes the groups owned by you operationId: deleteGroups tags: - groups parameters: - name: groups in: body description: Groups to remove as a comma-separated list of group identifiers; note that by not providing this parameter it means all groups owned by you are removed required: false schema: $ref: "#/definitions/GroupsPayload" responses: "200": description: Groups removing is OK (or no groups to remove) schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => a device is currently booked or unremovable built-in group * 404: Not Found => unknown groups * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] post: summary: Creates a group description: Creates a group with you as owner operationId: createGroup tags: - groups parameters: - name: group in: body description: Group properties; at least one property is required required: true schema: $ref: "#/definitions/GroupPayload" responses: "201": description: Group information schema: $ref: "#/definitions/GroupResponse" default: description: > Unexpected Error: * 400: Bad Request => invalid format or semantic of properties * 401: Unauthorized => bad credentials * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /groups/{id}: x-swagger-router-controller: groups get: summary: Gets a group description: Returns a group to which you belong operationId: getGroup tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: fields in: query description: Comma-separated list of group fields; only listed fields will be returned in response required: false type: string responses: "200": description: Group information schema: $ref: "#/definitions/GroupResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown group * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] put: summary: Updates a group description: Updates a group owned by you operationId: updateGroup tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: group in: body description: Group properties; at least one property is required required: true schema: $ref: "#/definitions/GroupPayload" responses: "200": description: Group information (an empty group is returned if no change is made) schema: $ref: "#/definitions/GroupResponse" "409": description: Conflicts information schema: $ref: "#/definitions/ConflictsResponse" default: description: > Unexpected Error: * 400: Bad Request => invalid format or semantic of properties * 401: Unauthorized => bad credentials * 403: Forbidden => quota is reached or unauthorized property * 404: Not Found => unknown group * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes a group description: Removes a group owned by you operationId: deleteGroup tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string responses: "200": description: Group removing is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => a device is currently booked or unremovable built-in group * 404: Not Found => unknown group * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /groups/{id}/devices: x-swagger-router-controller: groups get: summary: Gets the devices of a group description: Returns the devices of the group to which you belong operationId: getGroupDevices tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: bookable in: query description: Selects devices which could be potentially booked by that transient group (true => irrelevant for an origin group!), or selects all devices of the group (false); note that by not providing this parameter all devices of the group are selected type: boolean default: false - name: fields in: query description: Comma-separated list of device fields; only listed fields will be returned in response required: false type: string responses: "200": description: Group devices information schema: $ref: "#/definitions/DeviceListResponse" default: description: > Unexpected Error: * 400: Bad request => group is not transient * 401: Unauthorized => bad credentials * 404: Not Found => unknown group * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] put: summary: Adds devices into a transient group description: Adds devices into a transient group owned by you operationId: addGroupDevices tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: devices in: body description: Devices to add as a comma-separated list of serials; note that by not providing this parameter it means all devices which could be potentially booked by that transient group are added into the latter required: false schema: $ref: "#/definitions/DevicesPayload" responses: "200": description: Group information (an empty group is returned if no change is made) schema: $ref: "#/definitions/GroupResponse" "409": description: Conflicts information schema: $ref: "#/definitions/ConflictsResponse" default: description: > Unexpected Error: * 400: Bad Request => group is not transient * 401: Unauthorized => bad credentials * 403: Forbidden => quota is reached * 404: Not Found => unknown group or devices * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes devices from a transient group description: Removes devices from a transient group owned by you operationId: removeGroupDevices tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: devices in: body description: Devices to remove as a comma-separated list of serials; note that by not providing this parameter it means all devices of the group are removed required: false schema: $ref: "#/definitions/DevicesPayload" responses: "200": description: Group information (an empty group is returned if no change is made) schema: $ref: "#/definitions/GroupResponse" default: description: > Unexpected Error: * 400: Bad Request => group is not transient * 401: Unauthorized => bad credentials * 404: Not Found => unknown group or devices * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /groups/{id}/devices/{serial}: x-swagger-router-controller: groups get: summary: Gets a device of a group description: Returns a device of a group to which you belong operationId: getGroupDevice tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: serial in: path description: Device identifier (serial) required: true type: string - name: fields in: query description: Comma-separated list of device fields; only listed fields will be returned in response required: false type: string responses: "200": description: Group device information schema: $ref: "#/definitions/DeviceResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown group or device * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] put: summary: Adds a device into a transient group description: Adds a device into a transient group owned by you operationId: addGroupDevice tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: serial in: path description: Device identifier (serial) required: true type: string responses: "200": description: Group information (an empty group is returned if no change is made) schema: $ref: "#/definitions/GroupResponse" "409": description: Conflicts information schema: $ref: "#/definitions/ConflictsResponse" default: description: > Unexpected Error: * 400: Bad Request => group is not transient * 401: Unauthorized => bad credentials * 403: Forbidden => quota is reached * 404: Not Found => unknown group or device * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes a device from a transient group description: Removes a device from a transient group owned by you operationId: removeGroupDevice tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: serial in: path description: Device identifier (serial) required: true type: string responses: "200": description: Group information (an empty group is returned if no change is made) schema: $ref: "#/definitions/GroupResponse" default: description: > Unexpected Error: * 400: Bad Request => group is not transient * 401: Unauthorized => bad credentials * 404: Not Found => unknown group or device * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /groups/{id}/users: x-swagger-router-controller: groups get: summary: Gets the users of a group description: Gets the users of a group to which you belong; if you are the administrator user then all user fields are returned, otherwise only 'email', 'name' and 'privilege' user fields are returned operationId: getGroupUsers tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: fields in: query description: Comma-separated list of user fields; only listed fields will be returned in response required: false type: string responses: "200": description: Group users information schema: $ref: "#/definitions/UserListResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown group * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] put: summary: Adds users into a group description: Adds users into a group owned by you operationId: addGroupUsers tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: users in: body description: Users to add as a comma-separated list of emails; note that by not providing this parameter it means all available users are added into the group required: false schema: $ref: "#/definitions/UsersPayload" responses: "200": description: Group information (an empty group is returned if no change is made) schema: $ref: "#/definitions/GroupResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown group or device or users * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes users from a group description: Removes users from a group owned by you operationId: removeGroupUsers tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: users in: body description: Users to remove as a comma-separated list of emails; note that by not providing this parameter it means all users of the group are removed required: false schema: $ref: "#/definitions/UsersPayload" responses: "200": description: Group information (an empty group is returned if no change is made) schema: $ref: "#/definitions/GroupResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => owner or administrator user can't be removed * 404: Not Found => unknown group or device or users * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /groups/{id}/users/{email}: x-swagger-router-controller: groups get: summary: Gets a user of a group description: Gets a user of a group to which you belong; if you are the administrator user then all user fields are returned, otherwise only 'email', 'name' and 'privilege' user fields are returned operationId: getGroupUser tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: email in: path description: User identifier (email) required: true type: string - name: fields in: query description: Comma-separated list of user fields; only listed fields will be returned in response required: false type: string responses: "200": description: Group user information schema: $ref: "#/definitions/UserResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown group or device or user * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] put: summary: Adds a user into a group description: Adds a user into a group owned by you operationId: addGroupUser tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: email in: path description: User identifier (email) required: true type: string responses: "200": description: Group information (an empty group is returned if no change is made) schema: $ref: "#/definitions/GroupResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown group or device or user * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes a user from a group description: Removes a user from a group owned by you operationId: removeGroupUser tags: - groups parameters: - name: id in: path description: Group identifier required: true type: string - name: email in: path description: User identifier (email) required: true type: string responses: "200": description: Group information (an empty group is returned if no change is made) schema: $ref: "#/definitions/GroupResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => owner or administrator user can't be removed * 404: Not Found => unknown group or device or user * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /users: x-swagger-router-controller: users get: summary: Gets users description: gets users; if you are the administrator user then all user fields are returned, otherwise only 'email', 'name' and 'privilege' user fields are returned operationId: getUsers tags: - users parameters: - name: fields in: query description: Comma-separated list of user fields; only listed fields will be returned in response required: false type: string responses: "200": description: Users information schema: $ref: "#/definitions/UserListResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes users description: Removes users from the database operationId: deleteUsers tags: - admin parameters: - name: groupOwner in: query description: Allows or not the removing of each user depending respectively if the user is a group owner (true) or not (false); note that by not providing the groupOwner parameter it means an unconditionally removing required: false type: boolean - name: users in: body description: Users to remove as a comma-separated list of emails; note that by not providing this parameter it means all users are selected for removing required: false schema: $ref: "#/definitions/UsersPayload" responses: "200": description: Users removing is OK (or no users to remove) schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => administrator user can't be removed * 404: Not Found => unknown users * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /users/groupsQuotas: x-swagger-router-controller: users put: summary: Updates the default groups quotas of users description: Updates the default groups quotas allocated to each new user operationId: updateDefaultUserGroupsQuotas tags: - admin parameters: - name: number in: query description: Number of groups required: false type: integer minimum: 0 - name: duration in: query description: Total duration of groups (milliseconds) required: false type: integer minimum: 0 - name: repetitions in: query description: Number of repetitions per Group required: false type: integer minimum: 0 responses: "200": description: Administrator user information (an empty user is returned if no change is made) schema: $ref: "#/definitions/UserResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /users/{email}: x-swagger-router-controller: users post: summary: Creates a user description: Creates a user in the database operationId: createUser tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: name in: query description: User name required: true type: string responses: "201": description: User information schema: $ref: "#/definitions/UserResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => user already exists * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] get: summary: Gets a user description: Gets a user; if you are the administrator user then all user fields are returned, otherwise only 'email', 'name' and 'privilege' user fields are returned operationId: getUserByEmail tags: - users parameters: - name: email in: path description: User identifier (email) required: true type: string - name: fields in: query description: Comma-separated list of user fields; only listed fields will be returned in response required: false type: string responses: "200": description: User information schema: $ref: "#/definitions/UserResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown user * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes a user description: Removes a user from the database operationId: deleteUser tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: groupOwner in: query description: Allows or not the removing of the user depending respectively if the user is a group owner (true) or not (false); note that by not providing this parameter it means an unconditionally removing required: false type: boolean responses: "200": description: User removing is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => administrator user can't be removed * 404: Not Found => unknown user * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /users/{email}/groupsQuotas: x-swagger-router-controller: users put: summary: Updates the groups quotas of a user description: Updates the groups quotas of a user operationId: updateUserGroupsQuotas tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: number in: query description: Number of groups required: false type: integer minimum: 0 - name: duration in: query description: Total duration of groups (milliseconds) required: false type: integer minimum: 0 - name: repetitions in: query description: Number of repetitions per Group required: false type: integer minimum: 0 responses: "200": description: User information (an empty user is returned if no change is made) schema: $ref: "#/definitions/UserResponse" default: description: > Unexpected Error: * 400: Bad Request => quotas must be >= actual consumed resources * 401: Unauthorized => bad credentials * 404: Not Found => unknown user * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /users/{email}/devices: x-swagger-router-controller: users get: summary: Gets the devices controlled by a user description: Gets the devices controlled by a user operationId: getUserDevicesV2 tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: fields in: query description: Comma-separated list of device fields; only listed fields will be returned in response required: false type: string responses: "200": description: Controlled devices information schema: $ref: "#/definitions/DeviceListResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown user * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /users/{email}/devices/{serial}: x-swagger-router-controller: users post: summary: Places a device under user control description: Places a device under user control; note this is not completely analogous to press the 'Use' button in the UI because that does not authorize remote connection through ADB operationId: addUserDeviceV3 tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: serial in: path description: Device identifier (serial) required: true type: string - name: timeout in: query description: Means the device will be automatically removed from the user control if it is kept idle for this period (in milliseconds); default value is provided by the provider 'group timeout' required: false type: integer minimum: 0 responses: "200": description: Device controlling is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => Device is already controlled or is not available * 404: Not Found => unknown user or device * 500: Internal Server Error * 504: Gateway Time-out => device is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] get: summary: Gets a device controlled by a user description: Gets a device controlled by a user operationId: getUserDevice tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: serial in: path description: Device identifier (Serial) required: true type: string - name: fields in: query description: Comma-separated list of device fields; only listed fields will be returned in response required: false type: string responses: "200": description: Controlled device information schema: $ref: "#/definitions/DeviceResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is not controlled by the user * 404: Not Found => unknown user or device * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Remove a device from the user control description: Remove a device from the user control; note this is analogous to press the 'Stop Using' button in the UI because that forbids also remote connection through ADB operationId: deleteUserDevice tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: serial in: path description: Device identifier (serial) required: true type: string responses: "200": description: Device releasing is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is not controlled by the user * 404: Not Found => unknown user or device * 500: Internal Server Error * 504: Gateway Time-out => device is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /users/{email}/devices/{serial}/remoteConnect: x-swagger-router-controller: users post: summary: Allows to remotely connect to a device controlled by a user description: Allows to remotely connect to a device controlled by a user; returns the remote debug URL in response for use with ADB operationId: remoteConnectUserDevice tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: serial in: path description: Device identifier (serial) required: true type: string responses: "200": description: Remote debug URL schema: $ref: "#/definitions/RemoteConnectUserDeviceResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is not controlled by the user * 404: Not Found => unknown user or device * 500: Internal Server Error * 504: Gateway Time-out => device is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Forbids to remotely connect to a device controlled by a user description: Forbids using ADB to remotely connect to a device controlled by a user operationId: remoteDisconnectUserDevice tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: serial in: path description: Device identifier (serial) required: true type: string responses: "200": description: Remote debug URL disabling is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is not controlled by the user * 404: Not Found => unknown user or device * 500: Internal Server Error * 504: Gateway Time-out => device is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /users/{email}/accessTokens: x-swagger-router-controller: users post: summary: Create an access token for a user description: Creates an access token for a user. operationId: createUserAccessToken tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: title in: query description: Access token title required: true type: string responses: "200": description: Access token information schema: $ref: "#/definitions/UserAccessTokenResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown user * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] get: summary: Gets the access tokens of a user description: Gets the access tokens of a user operationId: getUserAccessTokensV2 tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string responses: "200": description: Access tokens information schema: $ref: "#/definitions/UserAccessTokensResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown user * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Remove the access tokens of a user description: Remove the access tokens of a user operationId: deleteUserAccessTokens tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string responses: "200": description: Access tokens removing is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown user * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /users/{email}/accessTokens/{id}: x-swagger-router-controller: users get: summary: Gets an access token of a user description: Gets an access token of a user operationId: getUserAccessToken tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: id in: path description: Access token identifier required: true type: string responses: "200": description: Access token information schema: $ref: "#/definitions/UserAccessTokenResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown user or token * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes an access token of a user description: Removes an access token of a user operationId: deleteUserAccessToken tags: - admin parameters: - name: email in: path description: User identifier (email) required: true type: string - name: id in: path description: Access token identifier required: true type: string responses: "200": description: Access token removing is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown user or token * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /user: x-swagger-router-controller: user get: summary: User Profile description: The User Profile endpoint returns information about current authorized user operationId: getUser tags: - user responses: "200": description: Current User Profile information schema: $ref: "#/definitions/UserResponse" default: description: Unexpected Error schema: $ref: "#/definitions/ErrorResponse" security: - accessTokenAuth: [] /user/devices: x-swagger-router-controller: user get: summary: User Devices description: The User Devices endpoint returns device list owner by current authorized user operationId: getUserDevices tags: - user parameters: - name: fields in: query description: Fields query parameter takes a comma seperated list of fields. Only listed field will be return in response required: false type: string responses: "200": description: Current User Devices List schema: $ref: "#/definitions/DeviceListResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] post: summary: Add a device to a user description: The User Devices endpoint will request stf server for a new device. operationId: addUserDevice tags: - user parameters: - name: device in: body description: Device to add required: true schema: $ref: "#/definitions/AddUserDevicePayload" responses: "200": description: Add User Device Status default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is already controlled or is not available * 404: Not Found => unknown device * 500: Internal Server Error * 504: Gateway Time-out => device is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /user/devices/{serial}: x-swagger-router-controller: user post: summary: Places a device under user control description: Places a device under user control; note this is not completely analogous to press the 'Use' button in the UI because that does not authorize remote connection through ADB operationId: addUserDeviceV2 tags: - user parameters: - name: serial in: path description: Device identifier (serial) required: true type: string - name: timeout in: query description: Means the device will be automatically removed from the user control if it is kept idle for this period (in milliseconds); default value is provided by the provider 'group timeout' required: false type: integer minimum: 0 responses: "200": description: Device controlling is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is already controlled or is not available * 404: Not Found => unknown device * 500: Internal Server Error * 504: Gateway Time-out => device is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] get: summary: User Device description: The devices enpoint return information about device owned by user operationId: getUserDeviceBySerial tags: - user parameters: - name: serial in: path description: Device Serial required: true type: string - name: fields in: query description: Fields query parameter takes a comma seperated list of fields. Only listed field will be return in response required: false type: string responses: "200": description: Device Information owned by user schema: $ref: "#/definitions/DeviceResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is not controlled by the user * 404: Not Found => unknown device * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Delete User Device description: The User Devices endpoint will request for device release from stf server. It will return request accepted if device is being used by current user operationId: deleteUserDeviceBySerial tags: - user parameters: - name: serial in: path description: Device Serial required: true type: string responses: "200": description: Delete User Device Status schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is not controlled by the user * 404: Not Found => unknown device * 500: Internal Server Error * 504: Gateway Time-out => device is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] # I do know this is against REST principal to use verb as endpoint. But I feel it is more easy to # understand in comparision of using PUT/PATCH /user/devices/{serial}/remoteConnect: x-swagger-router-controller: user post: summary: Remote Connect description: The device connect endpoint will request stf server to connect remotely operationId: remoteConnectUserDeviceBySerial tags: - user parameters: - name: serial in: path description: Device Serial required: true type: string responses: "200": description: Remote Connect User Device Request Status schema: $ref: "#/definitions/RemoteConnectUserDeviceResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is not controlled by the user * 404: Not Found => unknown device * 500: Internal Server Error * 504: Gateway Time-out => device is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Remote Disconnect description: The device connect endpoint will request stf server to disconnect remotely operationId: remoteDisconnectUserDeviceBySerial tags: - user parameters: - name: serial in: path description: Device Serial required: true type: string responses: "200": description: Remote Disonnect User Device Request Status schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 403: Forbidden => device is not controlled by the user * 404: Not Found => unknown device * 500: Internal Server Error * 504: Gateway Time-out => device is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /user/fullAccessTokens: x-swagger-router-controller: user get: summary: Gets your access tokens description: Gets your access tokens; note that all fields are returned in reponse including the 'id' one operationId: getAccessTokens tags: - user responses: "200": description: Access tokens information schema: $ref: "#/definitions/UserAccessTokensResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /user/accessTokens: x-swagger-router-controller: user post: summary: Create an access token description: Create an access token for you operationId: createAccessToken tags: - user parameters: - name: title in: query description: Access token title required: true type: string responses: "201": description: Access token information schema: $ref: "#/definitions/UserAccessTokenResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] get: summary: Access Tokens description: The Access Tokens endpoints returns titles of all the valid access tokens operationId: getUserAccessTokens tags: - user responses: "200": description: Access Tokens titles schema: $ref: "#/definitions/AccessTokensResponse" default: description: Unexpected Error schema: $ref: "#/definitions/ErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes your access tokens description: Removes your access tokens operationId: deleteAccessTokens tags: - user responses: "200": description: Access tokens removing is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /user/accessTokens/{id}: x-swagger-router-controller: user get: summary: Gets an access token description: Gets one of your access tokens operationId: getAccessToken tags: - user parameters: - name: id in: path description: Access token identifier required: true type: string responses: "200": description: Access token information schema: $ref: "#/definitions/UserAccessTokenResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown token * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes an access token description: Removes one of your access tokens operationId: deleteAccessToken tags: - user parameters: - name: id in: path description: Access token identifier required: true type: string responses: "200": description: Access token removing is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown token * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /user/adbPublicKeys: x-swagger-router-controller: user post: summary: Adb public keys description: Add adb public key for current user operationId: addAdbPublicKey consumes: - application/json produces: - application/json tags: - user parameters: - name: adb in: body schema: type: object required: - publickey properties: publickey: type: string description: adb public key (~/.android/id_rsa.pub) title: type: string description: By default will be extracted from public key responses: "200": description: Add adb key response default: description: Unexpected Error schema: $ref: "#/definitions/ErrorResponse" security: - accessTokenAuth: [] /devices: x-swagger-router-controller: devices get: summary: Device List description: The devices endpoint return list of all the STF devices including Disconnected and Offline operationId: getDevices tags: - devices parameters: - name: target in: query description: > Targets devices of your universe: * bookable - devices belonging to a bookable group * standard - devices belonging to a standard group * origin - all devices * standardizable - devices which are not yet booked including those belonging to a standard group * user (default value) - devices which are accessible by you at a given time type: string enum: - bookable - standard - origin - standardizable - user default: user - name: fields in: query description: Fields query parameter takes a comma seperated list of fields. Only listed field will be return in response required: false type: string responses: "200": description: Devices information schema: $ref: "#/definitions/DeviceListResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes devices description: Removes devices from the database operationId: deleteDevices tags: - admin parameters: - name: present in: query description: Allows or not the removing of each device depending respectively if the device is present (true) or not (false); note that by not providing this parameter it means an unconditional removing required: false type: boolean - name: booked in: query description: Allows or not the removing of each device depending respectively if the device is booked (true) or not (false); note that by not providing this parameter it means an unconditional removing required: false type: boolean - name: annotated in: query description: Allows or not the removing of each device depending respectively if the device is annotated (true) or not (false); note that by not providing this parameter it means an unconditional removing required: false type: boolean - name: controlled in: query description: Allows or not the removing of each device depending respectively if the device is controlled (true) or not (false); note that by not providing this parameter it means an unconditional removing required: false type: boolean - name: devices in: body description: Devices to remove as a comma-separated list of serials; note that by not providing this parameter it means all devices are selected for removing required: false schema: $ref: "#/definitions/DevicesPayload" responses: "200": description: Devices removing is OK (or no devices to remove) schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown devices * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /devices/{serial}: x-swagger-router-controller: devices get: summary: Device Information description: The devices serial enpoint return information about a single device operationId: getDeviceBySerial tags: - devices parameters: - name: serial in: path description: Device Serial required: true type: string - name: fields in: query description: Fields query parameter takes a comma seperated list of fields. Only listed field will be return in response required: false type: string responses: "200": description: Device Information schema: $ref: "#/definitions/DeviceResponse" default: description: Unexpected Error schema: $ref: "#/definitions/ErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes a device description: Removes a device from the database operationId: deleteDevice tags: - admin parameters: - name: serial in: path description: Device identifier (serial) required: true type: string - name: present in: query description: Allows or not the removing of the device depending respectively if the device is present (true) or not (false); note that by not providing this parameter it means an unconditional removing required: false type: boolean - name: booked in: query description: Allows or not the removing of the device depending respectively if the device is booked (true) or not (false); note that by not providing this parameter it means an unconditional removing required: false type: boolean - name: annotated in: query description: Allows or not the removing of the device depending respectively if the device is annotated (true) or not (false); note that by not providing this parameter it means an unconditional removing required: false type: boolean - name: controlled in: query description: Allows or not the removing of the device depending respectively if the device is controlled (true) or not (false); note that by not providing this parameter it means an unconditional removing required: false type: boolean responses: "200": description: Device removing is OK schema: $ref: "#/definitions/Response" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown device * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /devices/groups/{id}: x-swagger-router-controller: devices put: summary: Adds devices into an origin group description: Adds devices into an origin group along with updating each added device; returns the updated devices operationId: addOriginGroupDevices tags: - admin parameters: - name: id in: path description: Group identifier required: true type: string - name: devices in: body description: > Devices to add as a comma-separated list of serials; note that by not providing this parameter it means all 'available devices' are selected for adding: * 'availables devices' means all devices in case of a bookable group * 'availables devices' means all not yet booked devices in case of a standard group required: false schema: $ref: "#/definitions/DevicesPayload" - name: fields in: query description: Comma-seperated list of fields; only listed fields will be returned in response required: false type: string responses: "200": description: Devices information (an empty device list is returned if no change is made) schema: $ref: "#/definitions/DeviceListResponse" default: description: > Unexpected Error: * 400: Bad Request => group is not an origin one * 401: Unauthorized => bad credentials * 403: Fobidden => a device is currently booked * 404: Not Found => unknown group or devices * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending * 504: Gateway Time-out => server is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes devices from an origin group description: Removes devices from an origin group along with updating each removed device; returns the updated devices operationId: removeOriginGroupDevices tags: - admin parameters: - name: id in: path description: Group identifier required: true type: string - name: devices in: body description: Devices to remove as a comma-separated list of serials; note that by not providing this parameter it means all devices of the group are selected for removing required: false schema: $ref: "#/definitions/DevicesPayload" - name: fields in: query description: Comma-seperated list of fields; only listed fields will be returned in response required: false type: string responses: "200": description: Devices information (an empty device list is returned if no change is made) schema: $ref: "#/definitions/DeviceListResponse" default: description: > Unexpected Error: * 400: Bad Request => group is not an origin one * 401: Unauthorized => bad credentials * 403: Fobidden => a device is currently booked * 404: Not Found => unknown group or devices * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending * 504: Gateway Time-out => server is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /devices/{serial}/groups: x-swagger-router-controller: devices get: summary: Gets the groups to which the device belongs description: Gets the groups to which the device belongs operationId: getDeviceGroups tags: - admin parameters: - name: serial in: path description: Device identifier (serial) required: true type: string - name: fields in: query description: Comma-seperated list of fields; only listed fields will be returned in response required: false type: string responses: "200": description: Groups information schema: $ref: "#/definitions/GroupListResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown device * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /devices/{serial}/bookings: x-swagger-router-controller: devices get: summary: Gets the bookings to which the device belongs description: Gets the bookings (i.e. transient groups) to which the device belongs operationId: getDeviceBookings tags: - devices parameters: - name: serial in: path description: Device identifier (serial) required: true type: string - name: fields in: query description: Fields query parameter takes a comma seperated list of fields. Only listed field will be return in response required: false type: string responses: "200": description: Bookings information schema: $ref: "#/definitions/GroupListResponse" default: description: > Unexpected Error: * 401: Unauthorized => bad credentials * 404: Not Found => unknown device * 500: Internal Server Error schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /devices/{serial}/groups/{id}: x-swagger-router-controller: devices put: summary: Adds a device into an origin group description: Adds a device into an origin group along with updating the added device; returns the updated device operationId: addOriginGroupDevice tags: - admin parameters: - name: serial in: path description: Device identifier (serial) required: true type: string - name: id in: path description: Group identifier required: true type: string responses: "200": description: Device information schema: $ref: "#/definitions/DeviceResponse" default: description: > Unexpected Error: * 400: Bad Request => group is not an origin one * 401: Unauthorized => bad credentials * 403: Fobidden => the device is currently booked * 404: Not Found => unknown group or device * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending * 504: Gateway Time-out => server is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] delete: summary: Removes a device from an origin group description: Removes a device from an origin group along with updating the removed device; returns the updated device operationId: removeOriginGroupDevice tags: - admin parameters: - name: serial in: path description: Device identifier (serial) required: true type: string - name: id in: path description: Group identifier required: true type: string responses: "200": description: Device information schema: $ref: "#/definitions/DeviceResponse" default: description: > Unexpected Error: * 400: Bad Request => group is not an origin one * 401: Unauthorized => bad credentials * 403: Fobidden => the device is currently booked * 404: Not Found => unknown group or device * 500: Internal Server Error * 503: Service Unavailable => server too busy or a lock on a resource is pending * 504: Gateway Time-out => server is not responding schema: $ref: "#/definitions/UnexpectedErrorResponse" security: - accessTokenAuth: [] /swagger.json: x-swagger-pipe: swagger_raw definitions: UnexpectedErrorResponse: required: - success - description properties: success: type: boolean default: false description: type: string Response: required: - success - description properties: success: type: boolean default: true description: type: string GroupResponse: required: - success - description - group properties: success: type: boolean description: type: string group: description: A null value means the group is unchanged type: object Conflict: type: object properties: devices: description: Devices in conflict type: array items: type: string date: description: Timeslot in conflict type: object properties: start: type: string format: date-time stop: type: string format: date-time group: description: Name of the group in conflict type: string owner: description: Owner of the group in conflict type: object properties: email: type: string name: type: string ConflictsResponse: required: - success - description - conflicts properties: success: type: boolean description: type: string conflicts: description: > List of conflicts with the current group operation: * adding a device into the group * updating the schedule of the group type: array items: $ref: '#/definitions/Conflict' GroupListResponse: required: - success - description - groups properties: success: type: boolean description: type: string groups: type: array items: type: object UserListResponse: required: - success - description - users properties: success: type: boolean description: type: string users: type: array items: type: object UserResponse: required: - success - description - user properties: success: type: boolean description: type: string user: type: object Token: type: object properties: id: type: string title: type: string UserAccessTokenResponse: required: - success - description - token properties: success: type: boolean description: type: string token: $ref: '#/definitions/Token' UserAccessTokensResponse: required: - success - description - tokens properties: success: type: boolean description: type: string tokens: type: array items: $ref: '#/definitions/Token' AccessTokensResponse: required: - success - description - tokens properties: success: type: boolean description: type: string tokens: type: array items: type: string DeviceListResponse: required: - success - description - devices properties: success: type: boolean description: type: string devices: type: array items: type: object DeviceResponse: required: - success - description - device properties: success: type: boolean description: type: string device: type: object RemoteConnectUserDeviceResponse: required: - success - description - remoteConnectUrl properties: success: type: boolean description: type: string remoteConnectUrl: type: string AddUserDevicePayload: description: payload object for adding device to user required: - serial properties: serial: description: Device Serial type: string timeout: description: Device timeout in ms. If device is kept idle for this period, it will be automatically disconnected. Default is provider group timeout type: integer GroupPayload: description: Payload object for creating/updating a group properties: name: description: Group Name; default value => generated at runtime type: string pattern: '^[0-9a-zA-Z-_./: ]{1,50}$' startTime: description: Group starting time (in UTC, conforming to RFC 3339 section 5.6); default value => group creation time type: string format: date-time stopTime: description: Group expiration time (in UTC, conforming to RFC 3339 section 5.6); default value => startTime + 1 hour type: string format: date-time class: description: Group class; privileged value => debug, bookable, standard type: string enum: - once - bookable - hourly - daily - weekly - monthly - quaterly - halfyearly - yearly - debug - standard default: once repetitions: description: Group repetitions; default value => 0 type: integer minimum: 0 state: description: Group state; default value => pending or ready for bookable/standard classes type: string enum: - pending - ready GroupsPayload: description: Payload object for adding/removing groups properties: ids: description: Comma-separated list of identifiers type: string UsersPayload: description: Payload object for adding/removing users properties: emails: description: Comma-separated list of emails type: string DevicesPayload: description: Payload object for adding/removing devices properties: serials: description: Comma-separated list of serials type: string ErrorResponse: required: - message properties: message: type: string securityDefinitions: accessTokenAuth: type: apiKey name: authorization in: header