Camera firmware API

REST API for retrieving the status of the firmware and starting firmware upgrade on cameras.

{ "swagger": "2.0", "info": { "version": "2.2.0", "title": "Cameramanager API", "description": "RESTful API for the Cameramanager platform. API calls related to the camera's firmware." }, "host": "rest.cameramanager.com", "schemes": [ "http", "https" ], "basePath": "/rest/v2.2", "produces": [ "application/json" ], "definitions": { "Error": { "type": "object", "description": "Generic error response, modelled after RFC 7807.", "properties": { "code": { "type": "integer", "description": "Error code within the system." }, "title": { "type": "string", "description": "This title is not meant to be shown to users and is not guaranteed to stay the same. Please use the code to parse the error." }, "detail": { "type": "string", "description": "Error details, to help developers detect what went wrong." } }, "required": [ "code", "title" ] }, "OAuth2Error": { "type": "object", "description": "Generic OAuth2 error response when there is something wrong with the OAuth2 authentication. Defined at RFC 6749.", "properties": { "error": { "type": "string", "description": "A single ASCII error code conforming the pattern." }, "error_description": { "type": "string", "description": "Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred." } }, "required": [ "error" ] }, "CurrentFirmwareStatus": { "type": "string", "description": "Current status of the camera's firmware", "enum": [ "upgradable", "up-to-date", "upgrading", "unknown" ] }, "FirmwareStatus": { "type": "object", "properties": { "cameraId": { "type": "integer", "description": "Unique identifier for the camera." }, "currentVersion": { "type": "string", "description": "The firmware version currently installed in this camera." }, "targetVersion": { "type": "string", "description": "The firmware version this camera could be upgraded to." }, "status": { "$ref": "#/definitions/CurrentFirmwareStatus" } }, "required": [ "cameraId", "currentVersion", "targetVersion", "status" ] }, "FirmwareUpgradeReq": { "type": "object", "properties": { "currentVersion": { "type": "string", "description": "Target firmware version" } }, "required": [ "currentVersion" ] }, "CameraJob": { "description": "A job that was created to take some action with a camera that takes frequently too long to wait for.", "type": "object", "properties": { "jobId": { "description": "unique id of the job", "type": "string" }, "cameraId": { "description": "id of the camera this job", "type": "integer" }, "type": { "$ref": "#/definitions/CameraJobType" }, "status": { "$ref": "#/definitions/CameraJobStatus" }, "statusDetails": { "$ref": "#/definitions/CameraJobStatusDetails" }, "jobDetails": { "$ref": "#/definitions/CameraJobDetails" }, "creationTime": { "description": "Date and time the job was created at.", "type": "string", "format": "date-time" }, "startTime": { "description": "Date and time the job started running at.", "type": "string", "format": "date-time" }, "endTime": { "description": "Date and time the job ended at.", "type": "string", "format": "date-time" } }, "required": [ "jobId", "cameraId", "type", "status", "statusDetails", "jobDetails", "creationTime" ] }, "CameraJobType": { "description": "Type of job, for example:\n * camera.wifi.addNetwork: save a network to the camera and for most cameras: connect to the new network.\n * camera.wifi.connectNetwork: request the camera to connect to a given saved network.\n * camera.wifi.enableOrDisable: request the camera to toggle the wifi functionality.\n * camera.firmware.upgrade: request the camera to upgrade itself to a given firmware.", "type": "string", "enum": [ "camera.wifi.addNetwork", "camera.wifi.connectNetwork", "camera.wifi.enableOrDisable", "camera.firmware.upgrade" ] }, "CameraJobStatus": { "type": "string", "description": "Indicates the status of a job:\n * Created: the job has been created, but is not running yet.\n * Running: the job has been started and hasn't ended yet.\n * Ended: the job has been started and has ended.", "enum": [ "Created", "Running", "Ended" ] }, "CameraJobStatusDetails": { "type": "object", "description": "Represents details about the current status of the job. Most basic information after the job is done includes information on if it ended successfully or in case it didn't what error occurred. This object will be extended by jobs that want to give more details such as the firmware update job indicating how far it is in uploading the firmware, or at what state it is in the process of updating the camera. None of the fields is required as before the job has ended they are not available yet.", "properties": { "wasSuccessful": { "type": "boolean", "description": "Indicates if the job was generally successful or not." }, "errorType": { "type": "string", "description": "Code indicating a job was not successful. These are specific to the job, but some general examples:\n * internalError: The job failed because of an internal failure. Generally indicates the error was unexpected.\n * cameraError: The camera reacted with an unexpected error." }, "errorDescription": { "type": "string", "description": "A human readable description of the error, to be used by developers, not meant for end-users!" } } }, "CameraJobDetails": { "type": "object", "description": "Represents details on the arguments of the job as it was started. Each job type can extend this class to provide job specific information such as the target firmware version for a firmware upgrade or the target ssid for a wifi related job." }, "FirmwareUpgradeCameraJob": { "allOf": [ { "$ref": "#/definitions/CameraJob" }, { "type": "object", "properties": { "statusDetails": { "$ref": "#/definitions/FirmwareUpgradeCameraJobStatusDetails" }, "jobDetails": { "$ref": "#/definitions/FirmwareUpgradeCameraJobDetails" } } } ] }, "FirmwareUpgradeCameraJobStatusDetails": { "description": "Provides information about the state and progress of the firmware upgrade process.", "allOf": [ { "$ref": "#/definitions/CameraJobStatusDetails" }, { "type": "object", "properties": { "upgradeStatus": { "type": "string", "enum": [ "Initializing", "Uploading", "Upgrading", "Restarting", "Success", "Error", "Ping" ] }, "progress": { "$ref": "#/definitions/FirmwareUpgradeProgress" } }, "required": [ "upgradeStatus" ] } ] }, "FirmwareUpgradeProgress": { "description": "Provides the value of the current progress versus the value considered as 100% progress.", "type": "object", "properties": { "current": { "description": "current progress.", "type": "integer" }, "total": { "description": "value that is considered as 100% progress.", "type": "integer" } } }, "FirmwareUpgradeCameraJobDetails": { "allOf": [ { "$ref": "#/definitions/CameraJobDetails" }, { "type": "object", "properties": { "currentVersion": { "description": "the firmware version before the upgrade started.", "type": "string" }, "targetVersion": { "description": "the firmware version that the upgrade is requesting.", "type": "string" } } } ] } }, "responses": { "resourceNotFound": { "description": "Referenced resource could not be found.", "schema": { "$ref": "#/definitions/Error" } }, "unauthorized": { "description": "You are not authenticated. Please authenticate and try again.", "schema": { "$ref": "#/definitions/OAuth2Error" } }, "forbidden": { "description": "You have no permission to access the specified resource.", "schema": { "$ref": "#/definitions/Error" } }, "validationError": { "description": "The supplied object is invalid. Error detail will contain the validation error.", "schema": { "$ref": "#/definitions/Error" } }, "notAcceptableError": { "description": "The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.", "schema": { "$ref": "#/definitions/Error" } }, "internalServerError": { "description": "Something went wrong in the server. Please try again.", "schema": { "$ref": "#/definitions/Error" } }, "unsupportedCameraAction": { "description": "The camera does not support the requested action.", "schema": { "$ref": "#/definitions/Error" } }, "conflict": { "description": "There was a conflict while trying to perform your request. See error details for more information.", "schema": { "$ref": "#/definitions/Error" } }, "unsupportedMediaType": { "description": "The requested resource does not understand the media type sent in the request.", "schema": { "$ref": "#/definitions/Error" } } }, "parameters": { "cameraId": { "name": "cameraId", "in": "path", "description": "ID of the camera.", "required": true, "type": "integer" }, "status": { "name": "status", "in": "query", "description": "when set to 'upgradable' the response contains only those cameras whose firmware can be upgraded, when set to 'up-to-date' contains only those ones whose firmware is already up to date, when set to 'upgrading' contains only those ones whose firmware are upgrading. When not set returns all the firmware statuses of all the cameras.", "required": false, "type": "string", "enum": [ "upgradable", "up-to-date", "upgrading" ] } }, "paths": { "/cameras/{cameraId}/firmware": { "get": { "summary": "Get the firmware status for the given camera.", "description": "Retrieves the firmware status for the given camera. Firmware status is returned as one `FirmwareStatus` object.", "operationId": "getCameraFirmwareStatus", "parameters": [ { "$ref": "#/parameters/cameraId" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FirmwareStatus" } }, "400": { "$ref": "#/responses/unsupportedCameraAction" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CameraFirmware" ] }, "post": { "summary": "Start firmware upgrade for the given camera.", "description": "Starts firmware upgrade for the given camera. Returns a \"FirmwareUpgradeCameraJob\" to track the status of the request as firmware upgrade requests can take a long time (seconds to minutes) to complete.", "operationId": "upgradeFirmwareOfCamera", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "name": "firmwareUpgradeRequest", "in": "body", "required": true, "schema": { "$ref": "#/definitions/FirmwareUpgradeReq" } } ], "consumes": [ "application/json" ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/FirmwareUpgradeCameraJob" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "415": { "$ref": "#/responses/unsupportedMediaType" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CameraFirmware" ] } }, "/cameras/all/firmware": { "get": { "summary": "Get the list of firmware statuses for all cameras the user has access to.", "description": "Retrieves the list of all firmware statuses for all cameras the requesting user has access to. Firmware statuses are returned as a list of `FirmwareStatus` objects.", "operationId": "getAllCamerasFirmwareStatus", "parameters": [ { "$ref": "#/parameters/status" } ], "responses": { "200": { "description": "OK", "schema": { "title": "FirmwareStatuses", "type": "array", "items": { "$ref": "#/definitions/FirmwareStatus" } } }, "401": { "$ref": "#/responses/unauthorized" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CameraFirmware" ] } } } }
Camera Firmware API specification
swagger-firmware.yaml