Camera Wifi API

API specification

{ "swagger": "2.0", "info": { "version": "2.1.0", "title": "Cameramanager API", "description": "RESTful API for the Cameramanager platform. APIs related to camera Wi-Fi functionality. As these API will make calls to a camera, it could take some time (max 90 seconds) before we give a response." }, "host": "rest.cameramanager.com", "schemes": [ "http", "https" ], "basePath": "/rest/v2.1", "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.\n", "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.\n" } }, "required": [ "error" ] }, "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: * 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.", "type": "string", "enum": [ "camera.wifi.addNetwork", "camera.wifi.connectNetwork", "camera.wifi.enableOrDisable" ] }, "CameraJobStatus": { "type": "string", "description": "Indicates the status of a job: * 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: * 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." }, "WifiStatus": { "description": "Contains the wifi state of the camera. Will always include the status and the cameraId. When the status is equal to \"connected\", the SSID, encryption and strength of the wifi network are included.", "allOf": [ { "$ref": "#/definitions/WifiNetwork" }, { "type": "object", "properties": { "cameraId": { "type": "integer", "description": "Unique identifier for the camera." }, "status": { "$ref": "#/definitions/WifiConnectionState" }, "enabled": { "type": "boolean", "description": "Indicates wether the Wi-Fi functionality of the camera is enabled (true) or disabled (false)." } }, "required": [ "cameraId", "status" ] } ] }, "WifiStatusUpdate": { "type": "object", "description": "Object to be used to change the Wi-Fi state, currently mainly used to disable and enable the Wi-Fi functionality.", "properties": { "enabled": { "type": "boolean", "description": "Indicates wether the Wi-Fi functionality of the camera should be enabled (true) or disabled (false)" }, "networkId": { "type": "string", "description": "Id of the network as given in SavedWifiNetwork the camera should connect to." } } }, "WifiConnectionState": { "type": "string", "description": "Indicates the current status of the Wi-Fi functionality on the camera. Possible states include: * unsupported: the camera does not support this functionality.\n * disabled: the camera supports this functionality, but it has been disabled.\n * offline: the camera is currently offline.\n * unknown: the camera's current Wi-Fi status is unknown, likely because of a general error on the camera, please try again.\n * disconnected: the camera's Wi-Fi is currently not connected to a network.\n * connected: the camera currently has a working Wi-Fi connection.\n * connecting: the camera is currently trying to connect to a network it knows.\n * error: the camera is reporting some error with the Wi-Fi functionality.\n * accessPointMode: the camera's Wi-Fi is currently in \"access point mode\" which generally means it has created its own network for other devices to connect to.", "enum": [ "unsupported", "disabled", "offline", "unknown", "disconnected", "connected", "connecting", "error", "accessPointMode" ] }, "NewWifiNetwork": { "type": "object", "properties": { "ssid": { "type": "string", "description": "service set identifier for the network the camera should connect to." }, "password": { "type": "string", "description": "password that should be used to connect to the given network. Make sure it follows the requirements of the network's encryption type." } }, "required": [ "ssid" ] }, "WifiNetwork": { "type": "object", "properties": { "ssid": { "type": "string", "description": "service set identifier for the network the camera is currently connected to. Used as the unique identifier of a network." }, "strength": { "$ref": "#/definitions/ConnectionStrength" }, "encrypted": { "type": "boolean", "description": "Indicates if the network is encrypted in some way and thus if some key is necessary to connect. Does not indicate the strength of this encryption." } } }, "SavedWifiNetwork": { "allOf": [ { "$ref": "#/definitions/WifiNetwork" }, { "type": "object", "properties": { "id": { "type": "string" }, "preferred": { "type": "boolean" } }, "required": [ "ssid", "encrypted", "id", "preferred" ] } ] }, "ConnectionStrength": { "type": "string", "description": "connection strength of the network the camera is currently connected to. Not all cameras might report this value even if they are connected.", "enum": [ "high", "medium", "low" ] }, "WifiCameraJob": { "allOf": [ { "$ref": "#/definitions/CameraJob" }, { "type": "object", "properties": { "statusDetails": { "$ref": "#/definitions/WifiCameraJobStatusDetails" }, "jobDetails": { "$ref": "#/definitions/WifiCameraJobDetails" } } } ] }, "WifiCameraJobStatusDetails": { "description": "Currently Wi-Fi jobs do not provide any status information while the job is running.", "allOf": [ { "$ref": "#/definitions/CameraJobStatusDetails" } ] }, "WifiCameraJobDetails": { "allOf": [ { "$ref": "#/definitions/CameraJobDetails" }, { "type": "object", "properties": { "ssid": { "type": "string", "description": "SSID the camera should try to connect to." }, "keyProvided": { "type": "boolean", "description": "Indicates that a key (\"password\") was provided as credentials to connect to the network." } } } ], "required": [ "ssid", "keyProvided" ] }, "ConnectToWifiCameraJob": { "allOf": [ { "$ref": "#/definitions/CameraJob" }, { "type": "object", "properties": { "statusDetails": { "$ref": "#/definitions/ConnectToWifiCameraJobStatusDetails" }, "jobDetails": { "$ref": "#/definitions/ConnectToWifiCameraJobDetails" } } } ] }, "ConnectToWifiCameraJobStatusDetails": { "description": "Currently Wi-Fi jobs do not provide any status information while the job is running.", "allOf": [ { "$ref": "#/definitions/CameraJobStatusDetails" } ] }, "ConnectToWifiCameraJobDetails": { "allOf": [ { "$ref": "#/definitions/CameraJobDetails" }, { "type": "object", "properties": { "networkId": { "type": "string", "description": "ID of the saved wifi network the camera should try to connect to." } }, "required": [ "networkId" ] } ] } }, "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" } }, "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" } }, "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" } } }, "parameters": { "cameraId": { "name": "cameraId", "in": "path", "description": "ID of the camera.", "required": true, "type": "integer" }, "networkId": { "name": "networkId", "in": "path", "description": "ID of the network.", "required": true, "type": "string" }, "newNetwork": { "name": "newNetwork", "in": "body", "required": true, "schema": { "$ref": "#/definitions/NewWifiNetwork" } }, "accept": { "name": "accept", "in": "header", "required": true, "type": "string" } }, "paths": { "/cameras/{cameraId}/wifi/status": { "get": { "summary": "Get the Wi-Fi connection status for the given camera.", "description": "Retrieves the Wi-Fi connection status for the given camera. This status may be cached for 60 seconds and thus this information might be 60 seconds old at most. If the camera is offline, the status will be \"offline\".", "operationId": "getCameraWifiStatus", "parameters": [ { "$ref": "#/parameters/cameraId" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/WifiStatus" } }, "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": [ "CameraWifi" ] }, "patch": { "summary": "Request a Wi-Fi status update such as enabling or disabling the functionality or requesting the camera to connect to a certain known network.", "description": "Request a Wi-Fi status update, results in a bad request (http status code 400), if the camera doesn't support the given functionality. All successful requests result in a camera job. Currently supported changes (only one at a time): * Enable or disable the Wi-Fi functionality of the camera. Done by setting the \"enabled\" field to either true or false. Job type: \"camera.wifi.enableOrDisable\".\n * Request the camera to connect to a known network. Done by setting the \"ssid\" field to the ssid of a network in the list of known networks on the camera (Retrievable with GET /wifi/saved). Job type: \"camera.wifi.connectNetwork\".", "operationId": "updateCameraWifiStatus", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "name": "WifiStatusUpdate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/WifiStatusUpdate" } } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/WifiCameraJob" } }, "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": [ "CameraWifi" ] } }, "/cameras/{cameraId}/wifi/visible": { "get": { "summary": "Get a list of Wi-Fi networks currently visible to the camera.", "description": "Retrieves a list of Wi-Fi networks currently visible to the camera. This list is cached for 15 seconds and thus the results might be up to 15 seconds old. If the camera is offline, an error is returned with http status code 400 and error code 14.", "operationId": "getVisibleWifiNetworks", "parameters": [ { "$ref": "#/parameters/cameraId" } ], "responses": { "200": { "description": "OK", "schema": { "title": "WifiNetworks", "type": "array", "items": { "$ref": "#/definitions/WifiNetwork" } } }, "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": [ "CameraWifi" ] } }, "/cameras/{cameraId}/wifi/saved": { "get": { "summary": "Get a list of Wi-Fi networks saved to the camera.", "description": "Retrieves a list of Wi-Fi networks saved to the camera. If a network is saved to the camera, it means the camera is configured to connect to it if it is in range and the camera is not connected to another network. If multiple known networks are visible, the camera uses its own logic to decide which network to try to connect to.", "operationId": "getSavedWifiNetworks", "parameters": [ { "$ref": "#/parameters/cameraId" } ], "responses": { "200": { "description": "OK", "schema": { "title": "WifiNetworks", "type": "array", "items": { "$ref": "#/definitions/SavedWifiNetwork" } } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CameraWifi" ] }, "post": { "summary": "Save the given network to the camera and for most cameras request the camera to connect to the given network.", "description": "Save the given network to the camera and for most cameras: request the camera to connect to the given network. Returns a \"WifiCameraJob\" to track the status of the request as Wi-Fi connection requests can take a long time (seconds to minutes) to complete. Many cameras only support a single saved network at a time, in which case this request will result in the old one being overwritten. If a camera supports multiple saved networks, this request will overwrite any existing network with the same ssid.", "operationId": "addSavedNetwork", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/newNetwork" } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/WifiCameraJob" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "415": { "$ref": "#/responses/unsupportedMediaType" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CameraWifi" ] } }, "/cameras/{cameraId}/wifi/saved/{networkId}": { "put": { "summary": "Connect to an already saved network", "description": "Connect to an already saved network. Not all cameras are capable of this, in this case an error is returned with HTTP status code 400 and error code 11.", "operationId": "connectToSavedWifiNetwork", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/networkId" }, { "$ref": "#/parameters/accept" } ], "responses": { "200": { "description": "No content", "schema": { "$ref": "#/definitions/CameraJob" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CameraWifi" ] }, "delete": { "summary": "Remove a network from the set of saved networks on the camera.", "description": "Removes a network from the set of saved networks on the camera. Not all cameras are capable of this, in this case an error is returned with HTTP status code 400 and error code 11.", "operationId": "deleteSavedNetwork", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/networkId" } ], "responses": { "204": { "description": "No content" }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "CameraWifi" ] } } } }

swagger-camera-wifi.yml