--- #----------------------------------------------------------------------------------------------------------------------- # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance # with the License. A copy of the License is located at # # http://www.apache.org/licenses/LICENSE-2.0 # # or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES # OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions # and limitations under the License. #----------------------------------------------------------------------------------------------------------------------- #----------------------------------------------------------------------------------------------------------------------- # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance # with the License. A copy of the License is located at # # http://www.apache.org/licenses/LICENSE-2.0 # # or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES # OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions # and limitations under the License. #----------------------------------------------------------------------------------------------------------------------- openapi: 3.0.0 info: title: 'AWS Connected Device Framework: Asset Library' description: > The Asset Library service is a device registry that allows you to manage your fleet of devices within multiple hierarchical groups. Each one of the branches of the hierarchy can represent something meaningful to your business such as supplier, location, customer, vehicle, etc. The hierarchies within Asset Library are represented as `Groups`. Each Group has a single parent, but can comprise of many groups and/or devices as its members. `Devices` can be associated with one or more `Groups`, each with a named relationship to its group to give context. `Devices` themselves can be associated with other `Devices`, representing a composition type of relationship. Examples being a mote that comprises of a number of differnet sensors, or a car engine that is comprised of a number of different components. Different `Group Templates` can be created to align with your business, with each Group Template having its own attributes. An example Group Template could be a _Site_, with its _address_ being an example of an attribute. Likewise, `Device Templates` can be created to represent the different types of devices within your fleet, each with their own attributes. `Profiles` can be created and applied to device and groups to populate with default attirbutes and/or relations. `Policies` represent a document that can be attached to one or more groups within a hierarchy, and are automatically inherited by the devices and groups. version: 2.0.0 tags: - name: Devices description: > A `Device` represents a real world physical device that needs to be registered within the Asset Library, such as a sensor, switch, or a robotic arm. Each device is the equivalent of a `Thing` within AWS IoT. Devices can be attached to Groups within a hierarchy. A Device can represent an assembly of other Devices using the `component` relationship, where the device could optionally be represented as a `Thing` within AWS IoT also. Devices are identified by a unique `deviceId`. Devices comprise of a number of standard attributes, as well as custom attributes. Refer to the `Device Templates` section for further info. A Device may have the following state: - `unprovisioned`: The metadata for the device has been created, but the device has not yet been provisioned within AWS IoT - `active`: The device is active and available for use within AWS IoT - `decommissioned`: The device has been decommissioned, therefore is unable to connect to AWS IoT, though may be redeployed and recommissioned elsewhere - `retired`: The device has been retired, and has been removed from AWS IoT - name: Groups description: > A `Group` can represent both physical and logical groupings of devices and other groups. Examples of physical groups include locations and suppliers. Examples of logical groupings include bill of material structures. Groups can be constructured with a parent/child relationship to other groups, thus building up a hierarchy of groups. Device can then be associated to any group within the hierarchy. Groups are identified by a unique `path`. Groups comprise of a number of standard attributes, as well as custom attributes. Refer to the `Group Templates` section for further info. - name: Templates description: > Templates represent custom device and group templates that you define, each with their own attributes and constraints. Devices are identified by a unique `deviceId`, each have the following built-in attributes: - `templateId`: a specific device template that represents what custom attributes the device can have - `name`: name of the device - `description`: description of the device - `imageUrl`: URL of an image of the device - `awsIotThingArn`: the ARN to lookup devices that have been registered as Things within AWS IoT - `connected`: indicates whether the device is currently connected to AWS IoT - `state`: the state of the device (unprovisioned, active, decommissioned or retired) - `groups`: the paths of the groups that the device has been attached to - `attributes`: A key value map of attributes that have been created as part of defining a custom device template. When a Device is created as a component of another Device, it has all the same built-in attributes as described above with the exception of `groups`. Groups are identified by a unique `path`, and each have the following built-on attributes: - `templateId`: a specific group template that represents what custom attributes the group can have - `parentPath`: the path of the parent group that the group belongs to - `name`: name of the group - `description`: description of the group - `attributes`: A key value map of attributes that have been created as part of defining a custom group template. When defining the attributes of a custom device/group template, constraints can be applied using JSON Schema notation. Each of these custom attributes is accessible as `attributes.` within the custom device/group template. A simple example request body to register a new device template: { "properties": { "length": {"type": "number"}, "width": {"type": "number"}, "height": {"type": "number"} } } A more complex example request body to register a new device template: { "properties": { "length": { "type": "number", "minimum": 1, "maximum": 5 }, "width": { "type": "integer", "multipleOf": 2 }, "fleet": { "type": "string", "minLength": 5, "maxLength": 50 }, "firmware": { "type": "string", "pattern": "[abc]+" }, "ipAddress": { "type": "string", "format": "ipv4" }, "level": { "type": "string", "enum": ["low", "medium", "high"] } }, "required": ["fleet", "firmware", "ipAddress"] } - name: Profiles description: > A profile represents a set of default attributes and/or relations that can be applied to a device/group for a particular template. Multiple profiles can be created per template. - name: Policies description: > A policy represents a document that can be attached to one or more hierarchies, and then be inherited by any groups or devices that belong to all the hierarchies that the policy is applied to. A good use for policies is to look up appropriate documents or authorization levels based on a device or groups associations to specific hierarchies. As an example, let's say you need to apply different AWS IoT security policies when registering devices as Things depending upon their location. This would be handled by assigning a policy representing a provisoning template to different groups within a hierarchy representing the location. The appropriate provisioning template will be returned for the device/group depending on which and where in a hierarchy they are attached to. - name: Search description: > The search api allows you to search across both devices and groups applying a variety of different filters. Filters are applied via query parameters. To apply filters uisng an attribute from the item being returned specify in the format of `?filter=field:value`. To filter based on an attribute of a linked item, specify in the format of `?filter=relation:direction:field:value`. Multiple `relation:direction`'s may be specified to define paths between multiple linked items using the format `?filter=relation_1:direction_1:relation...:direction...:field:value`. URL Parameter | Description ---|--- `?eq=deviceId:MOD123` | 'deviceId' equals 'MOD123' `?lte=cycles:5` | 'cycles' less than or equals to 5 `?gt=located_at:out:qty:10` | 'qty' of the item linked via the outgoing 'located_at' relation is greater than 10 Multiple queries of the same type may be specified, for example if two equal filters are required: ?eq=deviceId:MOD123&eq=state:active paths: '/templates/device': get: tags: - Templates summary: List device templates description: Lists all device templates for a given status. operationId: listDeviceTemplates parameters: - $ref: '#/components/parameters/templateStatusQuery' - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' - $ref: '#/components/parameters/sortQuery' responses: '200': description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/TemplateInfoList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/TemplateInfoList' '400': $ref: '#/components/responses/BadRequest' '/templates/device/{templateId}': parameters: - $ref: '#/components/parameters/templateIdPath' post: tags: - Templates summary: > Registers a new device template within the system, using the JSON Schema standard to define the device template attributes and constraints. operationId: createDeviceTemplate requestBody: $ref: '#/components/requestBodies/TemplateDefinition' responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/ConcurrentModificationException' get: tags: - Templates summary: Find device template by ID description: Returns a single device template definition operationId: getDeviceTemplate parameters: - $ref: '#/components/parameters/templateStatusQuery' responses: '200': description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/TemplateInfo' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/TemplateInfo' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' patch: tags: - Templates summary: Update an existing device template. operationId: updateDeviceTemplate requestBody: $ref: '#/components/requestBodies/TemplateDefinition' responses: '204': description: OK '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ConcurrentModificationException' delete: tags: - Templates summary: Deletes an existing device template. operationId: deleteDeviceTemplate responses: '204': description: OK '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/templates/device/{templateId}/publish': parameters: - $ref: '#/components/parameters/templateIdPath' put: tags: - Templates summary: Publishes an existing device template. operationId: publishDeviceTemplate responses: '204': description: OK '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/templates/group': get: tags: - Templates summary: List group templates description: Lists all group templates for a given status. operationId: listGroupTemplates parameters: - $ref: '#/components/parameters/templateStatusQuery' - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' - $ref: '#/components/parameters/sortQuery' responses: '200': description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/TemplateInfoList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/TemplateInfoList' '400': $ref: '#/components/responses/BadRequest' '/templates/group/{templateId}': parameters: - $ref: '#/components/parameters/templateIdPath' post: tags: - Templates summary: > Registers a new group template within the system, using the JSON Schema standard to define the group template attributes and constraints. operationId: createGroupTemplate requestBody: $ref: '#/components/requestBodies/TemplateDefinition' responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' '500': $ref: '#/components/responses/ConcurrentModificationException' get: tags: - Templates summary: Find group template by ID description: Returns a single group template definition operationId: getGroupTemplate parameters: - name: status in: query description: Status of group template to return required: true schema: type: string enum: - draft - published responses: '200': description: OK content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/TemplateInfo' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/TemplateInfo' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' patch: tags: - Templates summary: Update an existing group template. operationId: updateGroupTemplate requestBody: $ref: '#/components/requestBodies/TemplateDefinition' responses: '204': description: OK '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ConcurrentModificationException' delete: tags: - Templates summary: Deletes an existing group template. operationId: deleteGroupTemplate responses: '204': description: OK '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/templates/group/{templateId}/publish': parameters: - $ref: '#/components/parameters/templateIdPath' put: tags: - Templates summary: Publishes an existing group template. operationId: publishGroupTemplate responses: '204': description: OK '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /devices: post: tags: - Devices summary: Add a new device to the asset library, adding it to the `/unprovisioned` group if no group is specified. operationId: createDevice parameters: - $ref: '#/components/parameters/applyProfileQuery' requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Device_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Device_2_0' description: Device to add to the asset library required: true responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' /bulkdevices: post: tags: - Devices summary: Adds a batch of devices in bulk to the asset library, adding them to the `/unprovisioned` group if no groups are specified. operationId: createDeviceBatch parameters: - $ref: '#/components/parameters/applyProfileQuery' requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/BulkDevices' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/BulkDevices' description: List of devices to add to the asset library required: true responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' patch: tags: - Devices summary: Update a batch of existing devices operationId: updateDeviceBatch parameters: - $ref: '#/components/parameters/applyProfileQuery' requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/BulkDevices' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/BulkDevices' description: List of devices and their attributes to update required: true responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' get: tags: - Devices summary: Find devices by ID description: Returns a batch of devices. operationId: bulkGetDevices parameters: - $ref: '#/components/parameters/deviceIdsQuery' - $ref: '#/components/parameters/expandComponentsQuery' - $ref: '#/components/parameters/attributesQuery' - $ref: '#/components/parameters/includeGroupsQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeviceList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/DeviceList' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/devices/{deviceId}': parameters: - $ref: '#/components/parameters/deviceIdPath' get: tags: - Devices summary: Find device by ID description: Returns a single device operationId: getDeviceByID parameters: - $ref: '#/components/parameters/expandComponentsQuery' - $ref: '#/components/parameters/attributesQuery' - $ref: '#/components/parameters/includeGroupsQuery' - $ref: '#/components/parameters/expandRelatedDevicesQuery' - $ref: '#/components/parameters/expandRelatedGroupsQuery' - $ref: '#/components/parameters/filterRelationsQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Device_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Device_2_0' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: tags: - Devices summary: Delete device of specified ID description: Deletes a single device operationId: deleteDevice responses: '204': description: successful operation '404': $ref: '#/components/responses/NotFound' patch: tags: - Devices summary: Update an existing device attributes operationId: updateDevice parameters: - name: applyProfile in: query description: Optionally apply a profile to the device to update unset attributes with attributes from the profile. schema: type: string requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Device_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Device_2_0' description: Device object that needs to be updated in device store required: true responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/devices/{deviceId}/{relationship}/groups': parameters: - $ref: '#/components/parameters/deviceIdPath' - $ref: '#/components/parameters/relationshipPath' get: tags: - Groups summary: List a devices related groups. operationId: listDeviceRelatedGroups parameters: - $ref: '#/components/parameters/templateQuery' - $ref: '#/components/parameters/directionQuery' - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' - $ref: '#/components/parameters/sortQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/GroupList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/GroupList' '404': $ref: '#/components/responses/NotFound' delete: tags: - Groups summary: Remove a device's associated groups operationId: detachFromGroups responses: '204': description: successful operation '404': $ref: '#/components/responses/NotFound' '/devices/{deviceId}/{relationship}/groups/{groupPath}': parameters: - $ref: '#/components/parameters/deviceIdPath' - $ref: '#/components/parameters/relationshipPath' - $ref: '#/components/parameters/groupPathPath' put: tags: - Devices summary: Associates a device to a group, giving context to its relationship. operationId: attachToGroup responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: tags: - Devices summary: Removes a device from an associated group operationId: detachFromGroup responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/devices/{deviceId}/{relationship}/{direction}/groups/{groupPath}': parameters: - $ref: '#/components/parameters/deviceIdPath' - $ref: '#/components/parameters/relationshipPath' - $ref: '#/components/parameters/directionPath' - $ref: '#/components/parameters/groupPathPath' put: tags: - Devices summary: Associates a device to a group, giving context to its relationship. operationId: attachToGroupWithDirection responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: tags: - Devices summary: Removes a device from an associated group operationId: detachFromGroupWithDirection responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/devices/{deviceId}/{relationship}/devices': parameters: - $ref: '#/components/parameters/deviceIdPath' - $ref: '#/components/parameters/relationshipPath' get: tags: - Devices summary: List a devices related devices. operationId: listDeviceRelatedDevices parameters: - $ref: '#/components/parameters/templateQuery' - $ref: '#/components/parameters/directionQuery' - $ref: '#/components/parameters/stateQuery' - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' - $ref: '#/components/parameters/sortQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeviceList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/DeviceList' '404': $ref: '#/components/responses/NotFound' delete: tags: - Devices summary: Remove a device's associated devices operationId: detachFromDevices responses: '204': description: successful operation '404': $ref: '#/components/responses/NotFound' '/devices/{deviceId}/{relationship}/devices/{otherDeviceId}': parameters: - $ref: '#/components/parameters/deviceIdPath' - $ref: '#/components/parameters/relationshipPath' - name: otherDeviceId in: path description: ID of device to create relationship to. required: true schema: type: string put: tags: - Devices summary: Associates a device to another device, giving context to its relationship. operationId: attachToDevice responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: tags: - Devices summary: Removes a device from an associated device operationId: detachFromDevice responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/devices/{deviceId}/{relationship}/{direction}/devices/{otherDeviceId}': parameters: - $ref: '#/components/parameters/deviceIdPath' - $ref: '#/components/parameters/relationshipPath' - $ref: '#/components/parameters/directionPath' - name: otherDeviceId in: path description: ID of device to create relationship to. required: true schema: type: string put: tags: - Devices summary: Associates a device to another device, giving context to its relationship. operationId: attachToDeviceWithDirection responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: tags: - Devices summary: Removes a device from an associated device operationId: detachFromDeviceWithDirection responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/devices/{deviceId}/components': parameters: - $ref: '#/components/parameters/deviceIdPath' post: tags: - Devices summary: Createa a new component and adds to the device. operationId: createComponent requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Device_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Device_2_0' description: Device to add as a component required: true responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' '/devices/{deviceId}/components/{componentId}': parameters: - $ref: '#/components/parameters/deviceIdPath' - $ref: '#/components/parameters/componentIdPath' patch: tags: - Devices summary: Updates the component of a device. operationId: updateComponent responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: tags: - Devices summary: Deletes a component of a devoce. operationId: deleteComponent responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /groups: post: tags: - Groups summary: Adds a new group to the device library as a child of the `parentPath` as specified in the request body. operationId: createGroup parameters: - $ref: '#/components/parameters/applyProfileQuery' requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Group_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Group_2_0' description: Group to add to the asset library required: true responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' /bulkgroups: post: tags: - Groups summary: Adds a batch of new group to the asset library as a child of the `parentPath` as specified in the request body. operationId: createGroupBatch parameters: - $ref: '#/components/parameters/applyProfileQuery' requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: type: array items: $ref: '#/components/schemas/BulkGroups' application/vnd.aws-cdf-v2.0+json: schema: type: array items: $ref: '#/components/schemas/BulkGroups' description: Group to add to the asset library required: true responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' get: tags: - Groups summary: Find Groups by Group Path description: Returns a batch of groups. operationId: bulkGetGroups parameters: - $ref: '#/components/parameters/groupPathsQuery' - $ref: '#/components/parameters/includeGroupsBooleanQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/GroupList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/GroupList' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/groups/{groupPath}': parameters: - $ref: '#/components/parameters/groupPathPath' - $ref: '#/components/parameters/includeGroupsBooleanQuery' get: tags: - Groups summary: Find group by Group's path description: Returns a single group operationId: getGroup responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Group_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Group_2_0' '404': $ref: '#/components/responses/NotFound' delete: tags: - Groups summary: Delete group with supplied path description: Deletes a single group operationId: deleteGroup responses: '204': description: successful operation '404': $ref: '#/components/responses/NotFound' patch: tags: - Groups summary: Update an existing group attributes, including changing its parent group. operationId: updateGroup parameters: - $ref: '#/components/parameters/applyProfileQuery' requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Group_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Group_2_0' description: Group object that needs to be updated required: true responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/groups/{groupPath}/members/devices': parameters: - $ref: '#/components/parameters/groupPathPath' get: tags: - Groups summary: List device members of group for supplied Group name description: Returns device members of group operationId: listGroupMembersDevices parameters: - $ref: '#/components/parameters/templateQuery' - $ref: '#/components/parameters/stateQuery' - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' - $ref: '#/components/parameters/sortQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeviceList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/DeviceList' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/groups/{groupPath}/members/groups': parameters: - $ref: '#/components/parameters/groupPathPath' get: tags: - Groups summary: List group members of group for supplied Group name description: Returns group members of group operationId: listGroupMembersGroups parameters: - $ref: '#/components/parameters/templateQuery' - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' - $ref: '#/components/parameters/sortQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/GroupList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/GroupList' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/groups/{groupPath}/memberships': parameters: - $ref: '#/components/parameters/groupPathPath' get: tags: - Groups summary: List all ancestor groups of a specific group. description: List all ancestor groups of a specific group. operationId: listGroupMemberships responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/GroupList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/GroupList' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/groups/{groupPath}/{relationship}/devices': parameters: - $ref: '#/components/parameters/groupPathPath' - $ref: '#/components/parameters/relationshipPath' get: tags: - Groups summary: List a groups related devices. operationId: listGroupRelatedDevices parameters: - $ref: '#/components/parameters/templateQuery' - $ref: '#/components/parameters/directionQuery' - $ref: '#/components/parameters/stateQuery' - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' - $ref: '#/components/parameters/sortQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeviceList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/DeviceList' '404': $ref: '#/components/responses/NotFound' '/groups/{groupPath}/{relationship}/groups': parameters: - $ref: '#/components/parameters/groupPathPath' - $ref: '#/components/parameters/relationshipPath' get: tags: - Groups summary: List a groups related groups. operationId: listGroupRelatedGroups parameters: - $ref: '#/components/parameters/templateQuery' - $ref: '#/components/parameters/directionQuery' - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' - $ref: '#/components/parameters/sortQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/GroupList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/GroupList' '404': $ref: '#/components/responses/NotFound' '/groups/{sourceGroupPath}/{relationship}/groups/{targetGroupPath}': parameters: - name: sourceGroupPath in: path description: Path of source group required: true schema: type: string - $ref: '#/components/parameters/relationshipPath' - name: targetGroupPath in: path description: Path of target group required: true schema: type: string put: tags: - Groups summary: Associates a group with another group, giving context to its relationship. operationId: attachGroupToGroup responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: tags: - Groups summary: Removes a group from an associated group operationId: detachGroupFromGroup responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/profiles/device/{templateId}': parameters: - $ref: '#/components/parameters/templateIdPath' post: tags: - Profiles summary: Adds a new device profile for a specific template. operationId: createDeviceProfile requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeviceProfile_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/DeviceProfile_2_0' description: Device Profile to add to the asset library required: true responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' get: tags: - Profiles summary: Return all device profiles for a specific template description: ReturnsReturn all device profiles for a specific template operationId: listDeviceProfiles responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeviceProfileList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/DeviceProfileList' '404': $ref: '#/components/responses/NotFound' '/profiles/device/{templateId}/{profileId}': parameters: - $ref: '#/components/parameters/templateIdPath' - $ref: '#/components/parameters/profileIdPath' get: tags: - Profiles summary: Retrieve a device profile description: Returns a single device profile operationId: getDeviceProfile responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeviceProfile_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/DeviceProfile_2_0' '404': $ref: '#/components/responses/NotFound' delete: tags: - Profiles summary: Delete a specific device profile description: Delete a specific device profile operationId: deleteDeviceProfile responses: '204': description: successful operation '404': $ref: '#/components/responses/NotFound' patch: tags: - Profiles summary: Update an existing device profile. operationId: updateDeviceProfile requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/DeviceProfile_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/DeviceProfile_2_0' description: Profile that needs to be updated required: true responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/profiles/group/{templateId}': parameters: - $ref: '#/components/parameters/templateIdPath' post: tags: - Profiles summary: Adds a new group profile for a specific template. operationId: createGroupProfile requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/GroupProfile_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/GroupProfile_2_0' description: Group Profile to add to the asset library required: true responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' get: tags: - Profiles summary: Return all group profiles for a specific template description: Return all group profiles for a specific template operationId: listGroupProfiles responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/GroupProfileList' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/GroupProfileList' '404': $ref: '#/components/responses/NotFound' '/profiles/group/{templateId}/{profileId}': parameters: - $ref: '#/components/parameters/templateIdPath' - $ref: '#/components/parameters/profileIdPath' get: tags: - Profiles summary: Retrieve a group profile description: Returns a single group profile operationId: getGroupProfile responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/GroupProfile_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/GroupProfile_2_0' '404': $ref: '#/components/responses/NotFound' delete: tags: - Profiles summary: Delete a specific group profile description: Delete a specific group profile operationId: deleteGroupProfile responses: '204': description: successful operation '404': $ref: '#/components/responses/NotFound' patch: tags: - Profiles summary: Update an existing group profile. operationId: updateGroupProfile requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/GroupProfile_1_0' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/GroupProfile_2_0' description: Profile that needs to be updated required: true responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /search: get: tags: - Search summary: Search for groups and devices. description: > Search results can be filtered by type, ancestorPath, and an arbitrary number of additional filter parameters. Each filter can reference a field of the search result, for example `eq=fieldname:value` or traverse the asset library graph to reference a related entry, for example `eq=traversal1:out:traversal2:in:fieldname:value`. All parameters are combined with a logical AND. For all search parameters that include a search key and search value separated by a colon (:) character, the HTTP parameter must be assembled using the following sequence of steps: 1. URL-encode the search value. 2. Concatenate the search key (incl. any traversals), the colon character, and result of step 1. 3. URL-encode the output of step 2. Failure to do so can yield incorrect search results for any search values that include the colon character. For example, a search for entries with an outgoing "manufactured_by" relation whose name starts with "Mfg+Asy Inc" should be expressed as: `/search?startsWith=manufactured_by%3Aout%3Aname%3AMfg%252BAsy%2520Inc` operationId: search parameters: - name: type in: query description: Type of group/device to filter for. This can be the high level `group` or `device`, as well as any custom group or device template that may have been registered. explode: true schema: type: array items: type: string - name: ntype in: query description: Type of group/device to filter out. This can be the high level `group` or `device`, as well as any custom group or device template that may have been registered. explode: true schema: type: array items: type: string - name: ancestorPath in: query description: The path of a common ancestor group to filter results by. schema: type: string - name: includeAncestor in: query description: Whether or not to include the ancestor in the search. Defaults to false explode: true schema: type: array items: type: string - name: eq in: query description: Filter an attribute based on an exact match. E.g. `?eq=firmwareVersion:ABC123` explode: true schema: type: array items: type: string - name: neq in: query description: Filter by an attribute based on not matching. E.g. `?neq=firmwareVersion:ABC123` explode: true schema: type: array items: type: string - name: lt in: query description: Filter an attribute based on having a value less than. E.g. `?lt=deploymentId:3` explode: true schema: type: array items: type: number - name: lte in: query description: Filter an attribute based on having a value less than or equal to. E.g. `?lte=deploymentId:3` explode: true schema: type: array items: type: number - name: gt in: query description: Filter an attribute based on having a value greater than. E.g. `?gt=deploymentId:3` explode: true schema: type: array items: type: number - name: gte in: query description: Filter an attribute based on having a value greater than or equal to. E.g. `?gte=deploymentId:3` explode: true schema: type: array items: type: number - name: startsWith in: query description: > Filter by an attribute based on starting with specific text. Case sensitive. For example: `?startsWith=model:MOD123` explode: true schema: type: array items: type: string - name: endsWith in: query description: > Filter by an attribute based on ending with specific text. Case sensitive. For example: `?endsWith=model:limited%20edition` explode: true schema: type: array items: type: string - name: contains in: query description: > Filter by an attribute based on ending with specific text. Case sensitive. For example: `?endsWith=model:quattro` explode: true schema: type: array items: type: string - name: exist in: query description: Return a match if the device/group in context has a matching relation/atrribute. E.g. `?exists=installed_in:out:groupPath:/vehicle/001` explode: true schema: type: array items: type: string - name: nexist in: query description: Return a match if the device/group in context does not have a matching relation/atrribute. E.g. `?nxists=installed_in:out:groupPath:/vehicle/001` explode: true schema: type: array items: type: string - name: facetField in: query description: Perform a faceted query. Specify in the format of `?facetField=relation:direction:field` schema: type: string - name: summarize in: query description: Summarize the search results by providing a total, instead of returning the results themselves. schema: type: boolean - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' - $ref: '#/components/parameters/sortQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: type: array items: $ref: '#/components/schemas/SearchResults' application/vnd.aws-cdf-v2.0+json: schema: type: array items: $ref: '#/components/schemas/SearchResults' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: tags: - Search summary: Search for groups and devices, and delete the results. description: > Search results can be filtered by type, ancestorPath, and an arbitrary number of additional filter parameters. Each filter can reference a field of the search result, for example `eq=fieldname:value` or traverse the asset library graph to reference a related entry, for example `eq=traversal1:out:traversal2:in:fieldname:value`. All parameters are combined with a logical AND. For all search parameters that include a search key and search value separated by a colon (:) character, the HTTP parameter must be assembled using the following sequence of steps: 1. URL-encode the search value. 2. Concatenate the search key (incl. any traversals), the colon character, and result of step 1. 3. URL-encode the output of step 2. Failure to do so can yield incorrect search results for any search values that include the colon character. For example, a search for entries with an outgoing "manufactured_by" relation whose name starts with "Mfg+Asy Inc" should be expressed as: `/search?startsWith=manufactured_by%3Aout%3Aname%3AMfg%252BAsy%2520Inc` operationId: deleteSearch parameters: - name: type in: query description: Type of group/device to filter for. This can be the high level `group` or `device`, as well as any custom group or device template that may have been registered. explode: true schema: type: array items: type: string - name: ntype in: query description: Type of group/device to filter out. This can be the high level `group` or `device`, as well as any custom group or device template that may have been registered. explode: true schema: type: array items: type: string - name: ancestorPath in: query description: The path of a common ancestor group to filter results by. schema: type: string - name: includeAncestor in: query description: Whether or not to include the ancestor in the search. Defaults to false explode: true schema: type: array items: type: string - name: eq in: query description: Filter an attribute based on an exact match. E.g. `?eq=firmwareVersion:ABC123` explode: true schema: type: array items: type: string - name: neq in: query description: Filter by an attribute based on not matching. E.g. `?neq=firmwareVersion:ABC123` explode: true schema: type: array items: type: string - name: lt in: query description: Filter an attribute based on having a value less than. E.g. `?lt=deploymentId:3` explode: true schema: type: array items: type: number - name: lte in: query description: Filter an attribute based on having a value less than or equal to. E.g. `?lte=deploymentId:3` explode: true schema: type: array items: type: number - name: gt in: query description: Filter an attribute based on having a value greater than. E.g. `?gt=deploymentId:3` explode: true schema: type: array items: type: number - name: gte in: query description: Filter an attribute based on having a value greater than or equal to. E.g. `?gte=deploymentId:3` explode: true schema: type: array items: type: number - name: startsWith in: query description: > Filter by an attribute based on starting with specific text. Case sensitive. For example: `?startsWith=model:MOD123` explode: true schema: type: array items: type: string - name: endsWith in: query description: > Filter by an attribute based on ending with specific text. Case sensitive. For example: `?endsWith=model:limited%20edition` explode: true schema: type: array items: type: string - name: contains in: query description: > Filter by an attribute based on ending with specific text. Case sensitive. For example: `?endsWith=model:quattro` explode: true schema: type: array items: type: string - name: exist in: query description: Return a match if the device/group in context has a matching relation/atrribute. E.g. `?exists=installed_in:out:groupPath:/vehicle/001` explode: true schema: type: array items: type: string - name: nexist in: query description: Return a match if the device/group in context does not have a matching relation/atrribute. E.g. `?nxists=installed_in:out:groupPath:/vehicle/001` explode: true schema: type: array items: type: string responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /policies: post: tags: - Policies summary: Creates a new `Policy`, and applies it to the provided `Groups`. operationId: createPolicy requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Policy' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Policy' description: Policy to create. required: true responses: '201': $ref: '#/components/responses/Created' '400': $ref: '#/components/responses/BadRequest' get: tags: - Policies summary: List policies, optionally filtered by policy type. operationId: listPolicies parameters: - name: type in: query description: Policy type to filter return schema: type: string - $ref: '#/components/parameters/offsetQuery' - $ref: '#/components/parameters/countQuery' responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: type: array items: $ref: '#/components/schemas/PolicyList' application/vnd.aws-cdf-v2.0+json: schema: type: array items: $ref: '#/components/schemas/PolicyList' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /policies/inherited: get: tags: - Policies summary: Returns all inherited `Policies` for a `Device` or set of `Groups` where the `Device`/`Groups` are associated with all the hierarchies that the `Policy` applies to. Either `deviceId` or `groupPath` must be provided. operationId: listInheritedPolicies parameters: - name: deviceId in: query description: ID of device to list policies schema: type: string - name: groupPath in: query description: Path of groups to list policies explode: true schema: type: array items: type: string - name: type in: query description: Policy type to return required: true schema: type: string responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: type: array items: $ref: '#/components/schemas/PolicyList' application/vnd.aws-cdf-v2.0+json: schema: type: array items: $ref: '#/components/schemas/PolicyList' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '/policies/{policyId}': parameters: - name: policyId in: path description: ID of policy required: true schema: type: string patch: tags: - Policies summary: Update the attributes of an existing policy. operationId: updatePolicy requestBody: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Policy' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Policy' description: Policy that needs to be updated required: true responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: tags: - Policies summary: Delete an existing policy. operationId: deletePolicy responses: '204': description: successful operation '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' get: tags: - Policies summary: Retrieve a specific policy. operationId: getPolicy responses: '200': description: successful operation content: application/vnd.aws-cdf-v1.0+json: schema: type: array items: $ref: '#/components/schemas/Policy' application/vnd.aws-cdf-v2.0+json: schema: type: array items: $ref: '#/components/schemas/Policy' '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' components: parameters: templateIdPath: in: path name: templateId description: ID of device template to publish required: true schema: type: string templateStatusQuery: name: status in: query description: Status of device template to return required: true schema: type: string enum: - draft - published deviceIdPath: in: path name: deviceId description: ID of device to return required: true schema: type: string profileIdPath: in: path name: profileId description: ID of profile required: true schema: type: string componentIdPath: in: path name: componentId description: ID of component required: true schema: type: string relationshipPath: in: path name: relationship description: The relationship between the device and group as defined by the device/group template. Where applicable, `%2A` (urlencoded `*`) may be used to return all. required: true schema: type: string groupPathPath: name: groupPath in: path description: Path of group. required: true schema: type: string applyProfileQuery: name: applyProfile in: query description: Optionally apply a profile to the device to update unset attributes with attributes from the profile. schema: type: string directionPath: name: direction in: path description: Direction of relation required: true schema: type: array items: type: string enum: - in - out - both default: out groupPathsQuery: name: groupPaths in: query description: Optionally only return group based on the paths. By default returns all attributes. schema: type: array items: type: string deviceIdsQuery: name: deviceIds in: query description: Optionally only return devices with these Ids. By default returns all attributes. schema: type: array items: type: string expandComponentsQuery: name: expandComponents in: query description: By default, components of a device are not returned. Passing `true` will return and expand a devices components. schema: type: boolean attributesQuery: name: attributes in: query description: Optionally only return these specific attributes. By default returns all attributes. schema: type: array items: type: string includeGroupsQuery: name: includeGroups in: query description: Optionally only return these specific related groups. By default returns all related groups. schema: type: array items: type: string includeGroupsBooleanQuery: name: includeGroups in: query description: Specify false to exclude the groups parameter from the response body schema: type: boolean default: true expandRelatedDevicesQuery: name: expandRelatedDevices in: query description: By default, only related device id's are returned. Passing `true` will return expanded related devices instead of just its device id. schema: type: boolean default: false expandRelatedGroupsQuery: name: expandRelatedGroups in: query description: By default, only related group paths are returned. Passing `true` will return expanded related groups instead of just its path. schema: type: boolean default: false filterRelationsQuery: name: filterRelations in: query description: Return related devices/groups filtered by relation. Specify the relation in the format of `{direction}:{relation}`, where `{direction}` may be `in`, `out` or `both`. explode: true schema: type: array items: type: string templateQuery: in: query name: template description: Optional filter to return a specific group template schema: type: string directionQuery: name: direction in: query description: Direction of relation explode: true schema: type: array items: type: string enum: - in - out - both default: out stateQuery: name: state in: query description: Return devices of a specific state schema: type: array items: type: string enum: - unprovisioned - active - decommissioned - retired default: active offsetQuery: in: query name: offset schema: type: integer minimum: 0 countQuery: in: query name: count schema: type: integer minimum: 0 sortQuery: in: query name: sort description: A comma delimited list of attributes to sort by, with an optional direction (`asc`/`desc') provided per attribute separated by a colon. Id not provided, `asc` is applied. schema: type: string examples: single_default_sort: value: deviceId summary: A single sort attribute, defaulting to ascending sort multiple_with_sort: value: state:asc,manufacturedAt:desc summary: Multiple attributes with direction specified. responses: Created: description: Created successfully headers: location: schema: type: string BadRequest: description: Invalid input content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Error' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/Error' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/Error' ConcurrentModificationException: description: ConcurrentModificationException schema: $ref: '#/components/schemas/Error' requestBodies: TemplateDefinition: content: application/vnd.aws-cdf-v1.0+json: schema: $ref: '#/components/schemas/TemplateDefinition' application/vnd.aws-cdf-v2.0+json: schema: $ref: '#/components/schemas/TemplateDefinition' required: true schemas: Entity: type: object properties: category: type: string description: Category of entity. enum: - group - device discriminator: propertyName: category Device: allOf: - $ref: '#/components/schemas/Entity' - type: object properties: deviceId: type: string description: Globally unique id of the Device. templateId: type: string description: Template of Device. description: type: string description: Description of the group. awsIotThingArn: type: string description: Arn of the device if registered within the AWS IoT registry. imageUrl: type: string description: URL of an image of the device. connected: type: boolean description: AWS IoT connectivity status state: type: string enum: - unprovisioned - active - decommissioned - retired description: The current state of the device assemblyOf: $ref: '#/components/schemas/Device' components: type: array description: The device components that this Device is assembled of. items: $ref: '#/components/schemas/Device' attributes: type: object additionalProperties: true relation: type: string description: Name of relation to this device (readonly, populated when displaying related devices only) direction: type: string description: Direction of relation (readonly, populated when displaying related devices only) enum: - in - out required: - deviceId - templateId Device_1_0: allOf: - $ref: '#/components/schemas/Device' - type: object properties: groups: description: Paths of the groups that this Device is associated with. type: object additionalProperties: type: array items: type: string devices: description: Ids of the devices that this Device is associated with. type: object additionalProperties: type: array items: type: string Device_2_0: allOf: - $ref: '#/components/schemas/Device' - type: object properties: groups: type: object properties: in: description: Paths of the incoming groups that this Device is associated with. type: object additionalProperties: type: array items: type: string out: description: Paths of the outgoing groups that this Device is associated with. type: object additionalProperties: type: array items: type: string devices: type: object properties: in: description: Ids of the incoming devices that this Device is associated with. type: object additionalProperties: type: array items: type: string out: description: Ids of the outgoing devices that this Device is associated with. type: object additionalProperties: type: array items: type: string DeviceProfile_1_0: allOf: - $ref: '#/components/schemas/Device_1_0' - type: object properties: profileId: type: string description: ID of the profile. required: - profileId - templateId DeviceProfile_2_0: allOf: - $ref: '#/components/schemas/Device_2_0' - type: object properties: profileId: type: string description: ID of the profile. required: - profileId - templateId Group: allOf: - $ref: '#/components/schemas/Entity' - type: object properties: groupPath: type: string description: Path of the group. templateId: type: string description: Template of group. Use 'Group' if no custom attributes are required. name: type: string description: name of group. parentPath: type: string description: Path of the groups parent. description: type: string description: Description of the group. attributes: type: object additionalProperties: true relation: type: string description: Name of relation to this group (readonly, populated when displaying related groups only) direction: type: string description: Direction of relation (readonly, populated when displaying related groups only) enum: - in - out required: - groupPath - templateId Group_1_0: allOf: - $ref: '#/components/schemas/Group' - type: object properties: groups: description: Paths of the groups that this Group is associated with. type: object additionalProperties: type: array items: type: string Group_2_0: allOf: - $ref: '#/components/schemas/Group' - type: object properties: groups: type: object properties: in: description: Paths of the incoming groups that this Group is associated with. type: object additionalProperties: type: array items: type: string out: description: Paths of the outgoing groups that this Group is associated with. type: object additionalProperties: type: array items: type: string GroupProfile_1_0: allOf: - $ref: '#/components/schemas/Group_1_0' - type: object properties: profileId: type: string description: ID of the profile. required: - profileId - templateId GroupProfile_2_0: allOf: - $ref: '#/components/schemas/Group_2_0' - type: object properties: profileId: type: string description: ID of the profile. required: - profileId - templateId BulkDevices: type: object properties: devices: type: array items: oneOf: - $ref: '#/components/schemas/Device_1_0' - $ref: '#/components/schemas/Device_2_0' BulkGroups: type: object properties: groups: type: array items: oneOf: - $ref: '#/components/schemas/Group_1_0' - $ref: '#/components/schemas/Group_2_0' GroupList: type: object properties: results: type: array items: oneOf: - $ref: '#/components/schemas/Group_1_0' - $ref: '#/components/schemas/Group_2_0' pagination: type: object properties: offset: type: integer count: type: integer total: type: number description: Total number of search results. Only returned by the search API's when `summarize` is set to true. DeviceList: type: object properties: results: type: array items: oneOf: - $ref: '#/components/schemas/Device_1_0' - $ref: '#/components/schemas/Device_2_0' pagination: type: object properties: offset: type: integer count: type: integer total: type: number description: Total number of search results. Only returned by the search API's when `summarize` is set to true. DeviceProfileList: type: object properties: results: type: array items: oneOf: - $ref: '#/components/schemas/DeviceProfile_1_0' - $ref: '#/components/schemas/DeviceProfile_2_0' pagination: type: object properties: offset: type: integer count: type: integer GroupProfileList: type: object properties: results: type: array items: oneOf: - $ref: '#/components/schemas/GroupProfile_1_0' - $ref: '#/components/schemas/GroupProfile_2_0' pagination: type: object properties: offset: type: integer count: type: integer SearchResults: type: object properties: results: type: array items: oneOf: - anyOf: - $ref: '#/components/schemas/Device_1_0' - $ref: '#/components/schemas/Group_1_0' - anyOf: - $ref: '#/components/schemas/Device_2_0' - $ref: '#/components/schemas/Group_2_0' TemplateInfoProperties: type: object required: ['type'] properties: type: type: array items: type: string enum: - integer - number - string - boolean - datettime - null enum: type: array items: type: string minLength: type: number maxLength: type: number pattern: type: string format: type: string enum: - date - date-time - uri - email - hostname - ipv4 - ipv6 minimum: type: number maximum: type: number exclusiveMinimum: type: number exclusiveMaximum: type: number multipleOf: type: number not: type: object oneOf: type: array items: type: object anyOf: type: array items: type: object allOf: type: array items: type: object TemplateInfo: type: object properties: templateId: description: Unique ID of template type: string category: description: Category of template type: string enum: - device - group properties: type: object additionalProperties: $ref: '#/components/schemas/TemplateInfoProperties' required: description: List of required properties type: array items: type: string relations: type: object properties: out: description: Map of defined relationships from this template to others type: object additionalProperties: type: array items: type: string in: description: Map of defined relationships from other templates to this type: object additionalProperties: type: array items: type: string TemplateInfoList: type: object properties: results: type: array items: $ref: '#/components/schemas/TemplateInfo' pagination: type: object properties: offset: type: integer count: type: integer TemplateDefinition: type: object properties: properties: description: Map of allowed properties (string, number, boolean and datetime types allowed only) type: object additionalProperties: type: string enum: - string - number - boolean - datettime required: description: List of required properties type: array items: type: string relations: type: object properties: out: description: Map of defined relationships from this template to others type: object additionalProperties: type: array items: oneOf: - type: string - type: object properties: name: type: string description: Name of relation includeInAuth: type: boolean description: If `true`, this relation will be used as part fo veriifying authorization when fine-grained access control is enabled. in: description: Map of defined relationships from other templates to this type: object additionalProperties: type: array items: oneOf: - type: string - type: object properties: name: type: string description: Name of relation includeInAuth: type: boolean description: If `true`, this relation will be used as part fo veriifying authorization when fine-grained access control is enabled. Policy: type: object properties: policyId: type: string description: unique ID of policy type: type: string description: type of policy description: type: string description: description of policy appliesTo: type: array description: the paths of the group that this policy applies to items: type: string document: type: string description: the policy document (e.g. a provisioning template) PolicyList: type: object properties: policies: type: array description: a list of policies items: $ref: '#/components/schemas/Policy' pagination: type: object properties: offset: type: integer count: type: integer Error: type: object properties: message: type: string