swagger: '2.0' info: version: '' title: SOTA Device Registry description: 'https://github.com/genivi/rvi_sota_server' license: name: Mozilla Public License url: 'https://github.com/genivi/rvi_sota_server/blob/master/LICENSE' host: 'localhost:8083' basePath: /api/v1 securityDefinitions: {} schemes: - http consumes: - application/json produces: - application/json paths: /devices: get: description: 'Get a list of all the devices, in alphabetical order by deviceName, in the namespace in the device registry.' parameters: - name: regex description: a regular expression to use when searching in: query required: false type: string - name: deviceId in: query required: false type: string - name: offset description: the offset into the list of devices in: query required: false type: integer format: int64 - name: ungrouped description: indicates to search for devices not belonging to a group (default is "false") in: query required: false type: boolean - name: limit description: the maximum amount of devices to return, after the offset in: query required: false type: integer format: int64 responses: 200: description: OK schema: type: object properties: total: description: The total number of results returnable type: integer format: int64 limit: description: The maximum number of results to be returned, after the offset type: integer format: int64 offset: description: The offset at which to begin returning results type: integer format: int64 values: type: array items: $ref: '#/definitions/Device' post: description: 'Register a new device with a name and an ID, get back its UUID' parameters: - name: DeviceT in: body required: true schema: $ref: '#/definitions/DeviceT' responses: 201: description: Created - The UUID of the newly-created device /devices/{uuid}: get: description: Get the device object for a single device parameters: - name: uuid description: The uuid of an existing device object in: path required: true type: string responses: 200: description: OK schema: $ref: '#/definitions/Device' delete: description: Delete a device parameters: - name: uuid description: The uuid of an existing device object in: path required: true type: string responses: 200: description: OK /mydevice/{uuid}/packages: put: description: | Mark a list of packages as installed on a device. Note that this does not install anything. It only updates device registry's database of installed packages. This endpoint is for ingesting the list of installed packages sent from the in-vehicle client. parameters: - name: uuid in: path description: The target uuid. required: true type: string - name: InstalledPackages in: body description: A complete list of the packages on the device. required: true schema: type: array items: $ref: '#/definitions/PackageId' responses: 200: description: OK /devices/{uuid}/packages: get: description: Return a list of packages installed on the device. parameters: - name: uuid in: path description: the vehicle uuid. required: true type: string - name: offset description: the offset into the list of packages in: query required: false type: integer format: int64 - name: limit description: the maximum amount of packages to return, after the offset in: query required: false type: integer format: int64 responses: 200: description: A list of all packages installed on the device schema: type: object properties: total: description: The total number of results returnable type: integer format: int64 limit: description: The maximum number of results to be returned, after the offset type: integer format: int64 offset: description: The offset at which to begin returning results type: integer format: int64 values: type: array items: $ref: '#/definitions/InstalledPackage' /devices/{uuid}/system_info: post: description: Create the system info for a device parameters: - name: uuid description: The uuid of an existing device object in: path required: true type: string - name: system description: The json object representing the system info in: body required: true schema: $ref: '#/definitions/SystemInfo' responses: 201: description: Created put: description: Update the system info for a device parameters: - name: uuid description: The uuid of an existing device object in: path required: true type: string - name: system description: The json object representing the system info in: body required: true schema: $ref: '#/definitions/SystemInfo' responses: 200: description: OK get: description: Retrieve the system info for a device parameters: - name: uuid description: The uuid of an existing device object in: path required: true type: string responses: 200: description: OK schema: $ref: '#/definitions/SystemInfo' /devices/{uuid}/groups: get: description: Retrieve the group memberships for a device parameters: - name: uuid description: The uuid of an existing device in: path required: true type: string - name: offset description: the offset into the list of devices in: query required: false type: integer format: int64 - name: limit description: the maximum amount of devices to return, after the offset in: query required: false type: integer format: int64 responses: 200: description: OK schema: type: object properties: total: description: The total number of results returnable type: integer format: int64 limit: description: The maximum number of results to be returned, after the offset type: integer format: int64 offset: description: The offset at which to begin returning results type: integer format: int64 values: type: array items: $ref: '#/definitions/Strings/properties/uuid' /device_groups: get: description: Returns a list of all groups responses: 200: description: OK post: description: Create a group for a namespace/groupName entry parameters: - name: groupName description: The name of the group of devices in: query required: true type: string responses: 201: description: Created /device_groups/{groupId}/rename: put: description: Rename a group parameters: - name: groupId description: The uuid of an existing group in: path required: true type: string - name: groupName description: The new name of the group in: query required: true type: string responses: 200: description: OK /device_groups/{groupId}/devices: get: description: return a list of device uuids in group parameters: - name: groupId description: The uuid of an existing group in: path required: true type: string - name: offset description: the offset into the list of devices in: query required: false type: integer format: int64 - name: limit description: the maximum amount of devices to return, after the offset in: query required: false type: integer format: int64 responses: 200: description: A list of the device uuids in the group schema: type: object properties: total: description: The total number of results returnable type: integer format: int64 limit: description: The maximum number of results to be returned, after the offset type: integer format: int64 offset: description: The offset at which to begin returning results type: integer format: int64 values: type: array items: $ref: '#/definitions/Strings/properties/uuid' /device_groups/{uuid}/count: get: description: return count of devices in group parameters: - name: uuid description: The uuid of an existing group in: path required: true type: string responses: 200: description: OK schema: type: integer /device_groups/{groupId}/devices/{deviceId}: post: description: add a device to a group parameters: - name: groupId description: The uuid of an existing group in: path required: true type: string - name: deviceId description: The uuid of an existing device in: path required: true type: string responses: 200: description: OK delete: description: remove a device from a group parameters: - name: groupId description: The uuid of an existing group in: path required: true type: string - name: deviceId description: The uuid of an existing device in: path required: true type: string responses: 200: description: OK /device_count/{name}/{version}/: get: description: returns count of groups and devices with the given package installed parameters: - name: name in: path description: The package name. required: true type: string - name: version in: path description: The package version. required: true type: string responses: 200: description: OK schema: $ref: '#/definitions/DevicesCount' /active_device_count: get: description: returns count of devices active during the given time interval (for an implicitely given namespace) parameters: - name: start in: query description: start time (inclusive) required: true type: string format: offsetDateTime - name: end in: query description: end time (exclusive) required: true type: string format: offsetDateTime responses: 200: description: OK schema: $ref: '#/definitions/ActiveDeviceCount' /device_packages/{name}: get: description: Get a count of devices on which the given package is installed, grouped by versions. parameters: - name: name in: path description: The package name. required: true type: string - name: offset description: the offset into the list of package stats in: query required: false type: integer format: int64 - name: limit description: the maximum amount of package stat objects to return, after the offset in: query required: false type: integer format: int64 responses: 200: description: A map of package versions to count. schema: type: object properties: total: description: The total number of results returnable type: integer format: int64 limit: description: The maximum number of results to be returned, after the offset type: integer format: int64 offset: description: The offset at which to begin returning results type: integer format: int64 values: type: array items: $ref: '#/definitions/PackageStat' definitions: DeviceT: type: object properties: deviceName: $ref: '#/definitions/Strings/properties/DeviceName' deviceId: $ref: '#/definitions/Strings/properties/DeviceId' deviceType: $ref: '#/definitions/Strings/properties/DeviceType' Device: type: object properties: namespace: $ref: '#/definitions/Strings/properties/namespace' deviceId: $ref: '#/definitions/Strings/properties/DeviceId' id: $ref: '#/definitions/Strings/properties/uuid' deviceName: $ref: '#/definitions/Strings/properties/DeviceName' deviceType: $ref: '#/definitions/Strings/properties/DeviceType' lastseen: type: string format: dateTime description: The last time a device uuid was seen by the SOTA server. createdAt: type: string format: dateTime description: The time the device was created activatedAt: type: string format: dateTime description: The time the device was activated SystemInfo: type: object description: A json object representing system info. No schema yet defined. CreateGroupRequest: type: object properties: device1: $ref: '#/definitions/Strings/properties/uuid' device2: $ref: '#/definitions/Strings/properties/uuid' groupName: type: string description: a group name between 1 and 100 characters long PackageId: type: object properties: name: type: string description: The package name. version: type: string description: The package version, in major.minor.patch notation by default. InstalledPackage: type: object properties: device: $ref: '#/definitions/Strings/properties/uuid' packageId: $ref: '#/definitions/PackageId' lastModified: type: string format: dateTime description: The last time a package installation was changed DevicesCount: type: object properties: deviceCount: type: integer description: count of devices with this package installed groupCount: description: a set containing all the group ids that have this package installed type: array items: $ref: '#/definitions/Strings/properties/uuid' ActiveDeviceCount: type: object properties: deviceCount: type: integer description: count of active devices (in a given interval) PackageStat: type: object description: A count of how many devices have a particular version of a package installed properties: packageVersion: type: string installedCount: type: integer Strings: type: object description: Various string types referenced elsewhere in the spec. properties: uuid: type: string description: 32 lowercase hexadecimal digits, displayed in five groups separated by hyphens DeviceId: type: string description: A 17-digit VIN. May contain only capital letters and digits. Cannot contain the letters I, O, or Q. DeviceName: type: string description: Custom name for a device DeviceType: type: string description: Valid values are "Vehicle" and "Other" namespace: type: string description: The namespace scope of the request. Default value is 'default'