swagger: '2.0' basePath: /api/deviceconfiguration/v3 info: title: Device Configuration API version: '3.0.1' x-visibility: 'external' description: Device Configuration API can be used to manage device configuration files and to coordinate configuration tasks for devices. The provided operations do not trigger any actions themselves, but are meant to be used by northbound applications to coordinate user and device efforts. Configuration tasks consist of different states that require the app operator user and the target device to participate in order to complete a task. Devices should use Deployment Workflow API to find out about configuration tasks. Device Configuration Service is based on Deployment Workflow Service and reflects all changes applied through Deployment Workflow API. Once a task is created in this API, it will be available also through Deployment Workflow API. The configuration task status can be advanced at this API or at Deployment Workflow API. x-templates: Pagination: &pageProperties page: type: object properties: size: type: integer format: int64 description: the number of records per page example: 20 totalElements: type: integer format: int64 description: the total number of rows/records example: 1 totalPages: type: integer format: int64 description: the total number of rows/records example: 1 number: type: integer format: int64 description: the current page number example: 0 StateInfo: &stateProperties entered: description: date and time when the state was first entered type: string format: date-time updated: description: date and time the state was last updated, will differ from "entered" if state is updated repeatedly type: string format: date-time progress: description: 'progress in current state as value in [0.0, 1.0]' type: number format: float minimum: 0 maximum: 1 message: type: string description: 'status message / info, free text from device' minLength: 0 maxLength: 200 details: type: object description: arbitrary block of json data, should be used to report additional information such as error details, stack traces, etc; max size in string representation is 20k minLength: 0 maxLength: 20000 Errors: invalidRequestError: &invalidRequestError code: mdsp.core.deviceconfiguration.invalidRequest logref: b16ac2e970c4c7329778c79b3e64e8ac message: Request is invalid emptyConfigFileListError: &emptyConfigFileListError code: mdsp.core.deviceconfiguration.configurationFileListEmpty logref: b16ac2e970c4c7329778c79b3e64e8ac message: Configuration File list in request body can not be empty. remoteOperationCreateTaskError: &remoteOperationCreateTaskError code: mdsp.core.deviceconfiguration.jobCreationFailed logref: b16ac2e970c4c7329778c79b3e64e8ac message: Remote operation failed while creating job. remoteOperationGetTaskError: &remoteOperationGetTaskError code: mdsp.core.deviceconfiguration.jobRetrievingFailed logref: b16ac2e970c4c7329778c79b3e64e8ac message: Remote operation failed while retrieving job. remoteOperationUpdateTaskError: &remoteOperationUpdateTaskError code: mdsp.core.deviceconfiguration.jobUpdatingFailed logref: b16ac2e970c4c7329778c79b3e64e8ac message: Remote operation failed while updating job. deviceNotFoundError: &deviceNotFoundError code: mdsp.core.devicemanagement.deviceNotFound logref: b16ac2e970c4c7329778c79b3e64e8ac message: Device not found invalidFilterError: &invalidFilterError code: mdsp.core.deviceconfiguration.invalidFilter logref: b16ac2e970c4c7329778c79b3e64e8ac message: State list must have at least 1 element taskNotFoundError: &taskNotFoundError code: mdsp.core.deploymentworkflow.instanceNotFound logref: b16ac2e970c4c7329778c79b3e64e8ac message: Requested task with id 0003b245-1d95-4e96-93bb-34261c424d90 can not be found. invalidStateTransitionError: &invalidStateTransitionError code: mdsp.core.deploymentworkflow.invalidStateTransition logref: b16ac2e970c4c7329778c79b3e64e8ac message: Transition from CONFIGURE to FAILED is not valid pathPrefixNotEmptyError: &pathPrefixNotEmptyError code: mdsp.core.deviceconfiguration.pathPrefixNotEmpty logref: b16ac2e970c4c7329778c79b3e64e8ac message: Given Path can not be empty pathNotEmptyError: &pathNotEmptyError code: mdsp.core.deviceconfiguration.pathNotEmpty logref: b16ac2e970c4c7329778c79b3e64e8ac message: Path can not be empty pathNotUniqueError: &pathNotUniqueError code: mdsp.core.deviceconfiguration.pathNotUnique logref: b16ac2e970c4c7329778c79b3e64e8ac message: The path/folder already exist pathNotValidError: &pathNotValidError code: mdsp.core.deviceconfiguration.pathNotValid logref: b16ac2e970c4c7329778c79b3e64e8ac message: Slash at the end of the path is not permitted fileNotFoundError: &fileNotFoundError code: mdsp.core.deviceconfiguration.fileNotFound logref: b16ac2e970c4c7329778c79b3e64e8ac message: Configuration file cannot be found revisionNotFoundError: &revisionNotFoundError code: mdsp.core.deviceconfiguration.revisionNotFound logref: b16ac2e970c4c7329778c79b3e64e8ac message: The revision cannot be found paths: /devices/{id}/configurationTasks: post: summary: Create new task description: > Create a new config deployment task. # Start of Execution # The newly created task will be in the CREATED state and thus not visible to the device. In order to start the execution of the task, update it to the CONFIGURE state. # Files # Each task refers to one or more files. Devices are expected to apply all files of a task in an "atomic" fashion (as far as this is feasible) The specified URI will be passed "as-is" to the device. Devices are expected to access this URI using Mindsphere credentials. Typically this URI will refer to a file in the Configuration File Storage, however it is possible to pass any URIs to the device as long as the device has the appropriate credentials to access the URI. # CustomData # The optional customData field can be used to pass arbitrary json data from the backend to the device in order. The backend will forward this information "as-is" to the device. tags: - Configuration Tasks security: - deviceConfiguration: - dvccfg.c consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/deviceId' - in: body name: taskDefinition description: task definition required: true schema: $ref: '#/definitions/TaskDefinition' responses: 'default': description: Other error with any status code and response body format. "201": description: The newly created task schema: $ref: '#/definitions/ConfigurationTask' "400": description: The request / sent data was invalid, see response body for more details schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *emptyConfigFileListError "409": description: Triggered remote operation failed, see response body for more details schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *remoteOperationCreateTaskError - <<: *deviceNotFoundError get: summary: List all tasks of a device description: > Returns a paginated list of all tasks of the specified device ordered by descending creation date (newest tasks first) tags: - Configuration Tasks security: - deviceConfiguration: - dvccfg.r produces: - application/json parameters: - $ref: '#/parameters/deviceId' - $ref: '#/parameters/size' - $ref: '#/parameters/page' - $ref: '#/parameters/sort' responses: 'default': description: Other error with any status code and response body format. "200": description: paginated list of tasks schema: $ref: '#/definitions/PaginatedConfigurationTask' /devices/{id}/configurationTasks/{taskId}: get: summary: Get task description: | Returns the specified task # Current State # The `currentState` field contains information about the current state in the state machine as well as the progress inside this state (if updated by the device) # History # The 'history' field contains a "trace" of all the past states this task was in, as well as the entry and exit times. It can be used to reconstruct the sequence of event/ actions that happend in this task. tags: - Configuration Tasks security: - deviceConfiguration: - dvccfg.r - edgeApi: - edge.use consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/deviceId' - $ref: '#/parameters/taskId' responses: 'default': description: Other error with any status code and response body format. "200": description: OK schema: $ref: '#/definitions/ConfigurationTask' "409": description: Triggered remote operation failed, see response body for more details schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *remoteOperationGetTaskError - <<: *taskNotFoundError patch: summary: Update a task description: > Updates the task. Updates must follow the state machine definition. Failing to do so will cause a 409 error tags: - Configuration Tasks security: - deviceConfiguration: - dvccfg.u - edgeApi: - edge.use produces: - application/json parameters: - $ref: '#/parameters/deviceId' - $ref: '#/parameters/taskId' - in: body name: ProgressReport description: Updated configuration required: true schema: $ref: '#/definitions/Updatetask' responses: 'default': description: Other error with any status code and response body format. "200": description: The updated task schema: $ref: '#/definitions/ConfigurationTask' "409": description: Triggered remote operation failed, see response body for more details schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *remoteOperationUpdateTaskError - <<: *invalidStateTransitionError /files: post: summary: Create a new empty file description: Create a new config file. The specified path must be unique (see general documentation about paths) tags: - Configuration Files security: - deviceConfigFiles: - dcfiles.c consumes: - application/json produces: - application/json parameters: - name: file description: configuration file object in: body required: true schema: $ref: '#/definitions/ConfigurationFile' responses: 'default': description: Other error with any status code and response body format. "201": description: The newly created file schema: $ref: '#/definitions/FileMetaData' "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError - <<: *pathNotEmptyError - <<: *pathNotUniqueError - <<: *pathNotValidError get: summary: List files description: >- Lists all files # Filtering / Searching # Using the `pathPrefix` query parameter, this endpoint can be used to look up the ids of files with a given path prefix. The supplied prefix will be compared with the `path` field of the file metadata. Users of the API should pick a naming scheme that allows efficient searching of files, e.g., using `{id}/{filename}.json` allows efficient listing of all files "belonging" to a specific device id. tags: - Configuration Files security: - deviceConfigFiles: - dcfiles.r consumes: - application/json produces: - application/json parameters: - name: pathPrefix in: query type: string required: true description: the prefix to search for - $ref: '#/parameters/size' - $ref: '#/parameters/page' - $ref: '#/parameters/sort' responses: 'default': description: Other error with any status code and response body format. "200": description: paginated list of all files (matching the specified prefix) schema: type: object properties: content: type: array items: $ref: '#/definitions/FileMetaData' <<: *pageProperties "400": description: Bad Request schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *invalidRequestError - <<: *pathPrefixNotEmptyError /files/{id}: get: summary: Get file metadata description: >- Returns the metadata of the specified file. # File Id to Path Mapping # To obtain the id of a file, the GET `files` endpoint can be used which allows looking up file ids based on a path prefix # File Metadata / File Content # This endpoint returns the metadata of the file. To access the content of the file, either use the `files/{id}/head` endpoint (to access the latest revision) or list all available revisions via `files/{id}/revisions` and access the content of a specific revision via `files/{id}/revisions/{hash}/content` tags: - Configuration Files security: - deviceConfigFiles: - dcfiles.r consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/fileId' responses: 'default': description: Other error with any status code and response body format. "200": description: The file metadata schema: $ref: '#/definitions/FileMetaData' "404": description: if file not found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *fileNotFoundError delete: summary: Delete file description: >- Deletes the specified file. This will also delete any revisions of this file and their content. # Idempotency # This endpoint provides idempotent deletes, i.e., repeated deletes to the same resource will always return 204 responses regardless whether the resource existed in the first place or not. tags: - Configuration Files security: - deviceConfigFiles: - dcfiles.d consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/fileId' responses: 'default': description: Other error with any status code and response body format. "204": description: Deletion successful, no content "404": description: if file not found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *fileNotFoundError /files/{id}/head: patch: summary: Update "head" description: >- Updates the "head" of this file, i.e., creates a new revision containing the data sent with the requests and updates the head resource to point to this new revision. Clients should use the If-Match header to safeguard against lost updates, i.e. concurrent access to the head resource # Content Metadata # Information about the content type and content length of the file are taken from the corresponding http header fields and must be correctly set by the client tags: - Configuration Files security: - deviceConfigFiles: - dcfiles.u consumes: - '*/*' produces: - application/json parameters: - $ref: '#/parameters/fileId' - $ref: '#/parameters/contentType' - name: content in: body description: Binary content of file. required: true schema: $ref: '#/definitions/Payload' responses: 'default': description: Other error with any status code and response body format. "200": description: Metadata of the updated "head" resource schema: $ref: '#/definitions/FileMetaData' "404": description: if file not found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *fileNotFoundError /files/{id}/revisions: post: summary: Create a new revision description: >- Creates a new revision containing the provided content. This endpoint will not update the "head" of the file to point to the new revision. # Content Metadata # Information about the content type and content length of the file are taken from the corresponding http header fields and must be correctly set by the client tags: - Configuration Files security: - deviceConfigFiles: - dcfiles.u consumes: - 'application/octet-stream' produces: - application/json parameters: - $ref: '#/parameters/fileId' - $ref: '#/parameters/contentType' - name: content description: Binary content of file. in: body required: true schema: $ref: '#/definitions/Payload' responses: 'default': description: Other error with any status code and response body format. "201": description: The newly created revision schema: $ref: '#/definitions/RevisionMetaData' "404": description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *fileNotFoundError get: summary: List revisions of a file description: >- Returns a paginated list of all revisions of the specified file. # File Metadata / File Content # This endpoint returns the metadata of the revision. To access the content use the`files/{id}/revisions/{hash}/content` endpoint tags: - Configuration Files security: - deviceConfigFiles: - dcfiles.r consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/fileId' - $ref: '#/parameters/size' - $ref: '#/parameters/page' - $ref: '#/parameters/sort' responses: 'default': description: Other error with any status code and response body format. "200": description: Paginated list of the revision metadata schema: type: object properties: content: type: array items: $ref: '#/definitions/RevisionMetaData' <<: *pageProperties "404": description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *fileNotFoundError /files/{id}/revisions/{hash}: get: summary: Get revision metadata description: Returns the metadata of the specified file revision tags: - Configuration Files security: - deviceConfigFiles: - dcfiles.r consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/fileId' - $ref: '#/parameters/hash' responses: 'default': description: Other error with any status code and response body format. "200": description: The requested metadata schema: $ref: '#/definitions/RevisionMetaData' "404": description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *fileNotFoundError - <<: *revisionNotFoundError /files/{id}/revisions/{hash}/content: get: summary: Get revision content description: >- Returns the content of the specified file revision. tags: - Configuration Files security: - deviceConfigFiles: - dcfiles.r consumes: - application/json produces: - '*/*' parameters: - $ref: '#/parameters/fileId' - $ref: '#/parameters/hash' - $ref: '#/parameters/acceptHeader' responses: 'default': description: Other error with any status code and response body format. "200": description: The file content "404": description: Not Found schema: $ref: '#/definitions/ErrorResponse' examples: Error responses occurring at this operation for invalid requests: errors: - <<: *fileNotFoundError - <<: *revisionNotFoundError definitions: TaskDefinition: type: object required: - files properties: files: type: array items: $ref: '#/definitions/ConfigurationFileReference' customData: type: object description: >- optional; arbitrary, user defined block of json containing additional information for the device additionalProperties: type: object example: sampleKey1: sampleValue1 sampleKey2: sampleValue2 target: type: object description: >- optional; arbitrary, user defined block of json containing target example: {"address": "XTOOLS"} ConfigurationFileReference: type: object required: - checksum - name - uri properties: name: type: string description: name of the file example: myFile.txt uri: type: string description: download URI example: 'http://...' checksum: type: string description: 'hash of the file in format `:`' example: 'sha1:cf23...' Updatetask: type: object required: - progress - state properties: state: type: string enum: - CONFIGURING - CONFIGURED - CANCELED - FAILED example: CONFIGURING progress: description: 'progress in current state as value in [0.0, 1.0]' type: number format: float minimum: 0 maximum: 1 message: type: string description: 'optional; status message / info, free text from device' minLength: 0 maxLength: 200 example: Configuring. details: type: object description: >- optional; arbitrary block of json data, should be used to report additional information such as error details, stack traces, etc; max size in string representation is 20k ConfigurationTask: type: object description: a configuration update task properties: id: description: unique id of the task type: string deviceId: description: unique id of the device owning the task type: string files: description: list of files to be updated as part of this task type: array items: $ref: '#/definitions/ConfigurationFileReference' customData: description: >- optional; arbitrary, user defined block of json containing additional information for the device additionalProperties: type: object example: sampleKey1: sampleValue1 sampleKey2: sampleValue2 createdAt: description: creation time of the task type: string format: date-time currentState: $ref: '#/definitions/ConfigurationStateInfo' target: $ref: '#/definitions/Target' history: description: list of history to be updated as part of this task type: array items: $ref: '#/definitions/ConfigurationStateInfo' transitions: description: list of history to be updated as part of this task type: array items: $ref: '#/definitions/Transition' Transition: type: object description: a transition state properties: from: description: current transition of the task type: string to: description: next transition of the task type: string PaginatedConfigurationTask: type: object description: paginated list of configuration update tasks properties: content: type: array items: $ref: '#/definitions/ConfigurationTask' <<: *pageProperties Payload: type: string format: binary description: Content of the file ConfigurationStateInfo: type: object description: information about a single state of the state machine properties: <<: *stateProperties state: type: string example: CONFIGURE description: name of the state enum: - CREATED - CONFIGURE - CONFIGURING - CONFIGURED - CANCELED - FAILED Target: type: object description: target of the task in the device properties: address: description: target address of the task in the device type: string example: XTOOLS ConfigurationFile: type: object required: - path properties: path: type: string description: unique "path" of the file example: /mydevice/network.json description: type: string description: optional description of the file's content or purpose example: network configuration settings such as ip address FileMetaData: type: object properties: description: type: string head: type: string id: type: string path: type: string RevisionMetaData: type: object properties: hash: type: string description: the hash of the file revision, also serves as unique identifier of the revision (content based addressing) example: 89fdde0b283... fileId: type: string description: the id of the file this revision belongs to example: 986073... contentLength: type: integer format: int32 description: length of the content (=file size in bytes) example: 105 maximum: 10485760 contentType: type: string description: content type of the content as used by http (MIME type + charset or other attributes) example: text/html; charset=utf-8 ErrorResponse: type: object properties: errors: type: array items: $ref: '#/definitions/Error' Error: type: object properties: code: type: string description: identifier code for the reason of the error logref: type: string description: log correlation ID message: type: string description: error message parameters: deviceId: name: id in: path description: Id of the device that owns the task. required: true type: string taskId: name: taskId in: path description: Id of the task required: true type: string fileId: name: id in: path type: string required: true description: the ID of the file contentType: name: Content-Type in: header type: string required: false description: Defines the accept header value to be used when retrieving the content default: application/octet-stream acceptHeader: name: Accept in: header type: string required: false description: If provided, must equal Content-Type provided while uploading hash: name: hash in: path type: string required: true description: the hash, also serves as id of the revision size: name: size in: query type: integer format: int32 default: 10 description: The maximum number of elements returned in one page page: name: page in: query type: integer format: int32 default: 0 description: The (0-based) index of the page sort: name: sort in: query type: string description: The order in which the elements are returned. Multiple fields could be used spearated by comma tags: - name: Configuration Tasks description: Create, update and list tasks for devices - name: Configuration Files description: Manage (revisions) of config files securityDefinitions: deviceConfiguration: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: dvccfg.c: Permission to create new tasks dvccfg.r: Permission to view / list update tasks and configuration status dvccfg.u: Permission to modify / update tasks and configuration status dvccfg.d: Permission to delete tasks and configuration status edgeApi: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: edge.use : Permission to use a device side API deviceConfigFiles: type: oauth2 authorizationUrl: http://UAA_DOMAIN/oauth/authorize tokenUrl: http://UAA_DOMAIN/oauth/token flow: accessCode scopes: dcfiles.c : Permission to create device configuration files dcfiles.r : Permission to read device configuration files / revisions dcfiles.u : Permission to update device configuration files / revisions dcfiles.d : Permission to delete device configuration files / revisions