Edge Storages

-------- THIS API IS NOT RELEASED YET ---------

{ "swagger": "2.0", "info": { "version": "2.4.0", "title": "Eagle Eye CameraManager API", "description": "RESTful API for the Eagle Eye CameraManager platform." }, "host": "rest.cameramanager.com", "schemes": [ "http", "https" ], "basePath": "/rest/v2.4", "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" ] }, "EdgeStorageState": { "type": "string", "description": "state: edge storage state of the camera, if the storage is seen by the camera and can be used or not:\n * `notDetected` - No SD card or HDD detected, or the network attached storage has not been configured.\n * `detected` - Signal that the storage is ready to be mounted.\n * `busy` - System is preparing edge storage to be used. Example of preparations are determining partitions and their formats, formatting unformatted/badly formatted partitions and finally mounting the partitions.\n * `ready` - Edge storage is ready to be used by the device. This is a final state\n * `error` - SD card hardware or HDD access hardware, or network attached storage subsystem fails. See field SubState for more details. This is a\nfinal state.", "enum": [ "notDetected", "detected", "busy", "ready", "error" ] }, "EdgeStorageSubState": { "type": "string", "description": "subState: further description of the edge storage state of the camera:\n * `readOnly` - the storage is set to be 'read-only'. This error mainly relates to when mounting physical SDCard\n * `notFormatted` - the storage is not formatted.\n * `badCredentials` - credentials used to configure storage are wrong.\n * `unknownHost` - credentials used to configure storage are wrong.\n * `hardwareError` - storage encountered an hardware issue while being written.\n * `unknown` - the reason the error occurred is unknown.\n * `none` - indicates that no extra details are provided.", "enum": [ "readOnly", "notFormatted", "badCredentials", "unknownHost", "hardwareError", "unknown", "none" ] }, "EdgeStorageHealth": { "type": "string", "description": "Status: The health of the edge storage of the camera:\n * `ok` - storage is in healthy conditions, meaning no interruptions are expected to happen in the near future.\n * `notOk` - interruptions or breakage of the storage can occur anytime in the near future.\n * `unknown` - health functionality is not supported or its state is unknown.", "enum": [ "ok", "notOk", "unknown" ] }, "EdgeRecordingRotationPolicy": { "type": "string", "description": "policy: The logic applied for recording rotation on the edge storage location:\n * `daily` - all recordings in the storage created more than X days ago will be deleted. X is the rotation days.\n * `diskSize` - the device deletes the oldest recordings in storage when no new space is available for new recordings.", "enum": [ "daily", "diskSize" ] }, "EdgeRecordingTriggerType": { "type": "string", "enum": [ "eventBased", "continuous" ] }, "EdgeRecordingTriggerConfigEventType": { "type": "string", "enum": [ "audio", "pir", "vmd", "apiTriggered" ] }, "EdgeRecordingRotationConfig": { "type": "object", "properties": { "rotationPolicy": { "$ref": "#/definitions/EdgeRecordingRotationPolicy" }, "rotationDays": { "type": "integer", "description": "Integer number greater than 0, this field is mandatory if rotation value is daily." } } }, "EdgeRecordingTriggerConfig": { "type": "object", "description": "Configuration applicable only for eventBased recording type. There can only be one config with a given type value in the list, an update of more than one type will result in a 400 error.", "properties": { "preRecordingDurationSeconds": { "type": "integer", "description": "seconds to record before the event." }, "postRecordingDurationSeconds": { "type": "integer", "description": "seconds to record after the event." }, "recordingDurationSeconds": { "type": "integer", "description": "seconds to record the event." }, "type": { "$ref": "#/definitions/EdgeRecordingTriggerConfigEventType" } } }, "EdgeStorage": { "type": "object", "properties": { "storageId": { "type": "integer", "description": "Unique identifier for the edge storage location" }, "name": { "type": "string", "description": "String identifying the storage. The value must be unique across all storage locations of the same device and cannot be modified by the user." }, "state": { "$ref": "#/definitions/EdgeStorageState" }, "subState": { "$ref": "#/definitions/EdgeStorageSubState" }, "sizeTotalMiB": { "type": "string", "description": "the total size of the storage in MebiBytes or unknown, if not applicable. A network file storage might not provide this info." }, "sizeInUseMiB": { "type": "string", "description": "the size of storage currently in use by the device in MebiBytes or unknown, if not applicable." }, "encrypted": { "type": "boolean", "description": "true if the encryption is enabled. false otherwise." }, "isRecording": { "type": "boolean", "description": "true if being recorded on edge storage." }, "health": { "$ref": "#/definitions/EdgeStorageHealth" }, "brand": { "type": "string", "description": "the brand of the storage or unknown otherwise" }, "model": { "type": "string", "description": "the model of the storage or unknown otherwise." } }, "required": [ "storageId", "name", "state", "subState" ] }, "EdgeRecordingConfiguration": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "if true, the recording on edge storage is enabled." }, "rotationConfig": { "$ref": "#/definitions/EdgeRecordingRotationConfig" }, "triggerType": { "$ref": "#/definitions/EdgeRecordingTriggerType" }, "triggerConfig": { "type": "array", "items": { "$ref": "#/definitions/EdgeRecordingTriggerConfig" } } }, "required": [ "enabled", "policy", "triggerType" ] }, "EdgeRecordingConfigurationUpdate": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "if true, the recording on edge storage is enabled." }, "rotationConfig": { "$ref": "#/definitions/EdgeRecordingRotationConfig" }, "triggerType": { "$ref": "#/definitions/EdgeRecordingTriggerType" }, "triggerConfig": { "type": "array", "items": { "$ref": "#/definitions/EdgeRecordingTriggerConfig" } } } }, "RecordingSyncJobParams": { "type": "object", "properties": { "syncStartTime": { "type": "string", "format": "date-time" }, "syncEndTime": { "type": "string", "format": "date-time" } } }, "RecordingSyncJob": { "allOf": [ { "$ref": "#/definitions/CameraJob" }, { "type": "object", "properties": { "statusDetails": { "$ref": "#/definitions/CameraJobStatusDetails" }, "jobDetails": { "$ref": "#/definitions/RecordingSyncCameraJobDetails" } } } ] }, "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:\n * camera.storageLocations.syncRecording: request to sync the recording from the edge storage location of the camera to the cloud", "type": "string", "enum": [ "camera.storageLocations.syncRecording" ] }, "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." }, "RecordingSyncCameraJobDetails": { "allOf": [ { "$ref": "#/definitions/CameraJobDetails" }, { "$ref": "#/definitions/RecordingSyncJobParams" } ] } }, "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" } } }, "parameters": { "cameraId": { "name": "cameraId", "in": "path", "description": "ID of the camera.", "required": true, "type": "integer" }, "storageId": { "name": "storageId", "in": "path", "description": "ID of the edge storage location.", "required": true, "type": "integer" } }, "paths": { "/cameras/{cameraId}/edgeStorages": { "get": { "summary": "Get edge storage info of the camera", "description": "Retrieves information of all the edge storage locations on the camera. It returns an empty list if there are no locations defined. It returns a bad request (http status code 400), if the camera doesn't support edge storage. It returns conflict (http status code 409) if camera is offline.", "operationId": "getEdgeStorages", "parameters": [ { "$ref": "#/parameters/cameraId" } ], "responses": { "200": { "description": "OK", "schema": { "title": "EdgeStorages", "type": "array", "items": { "$ref": "#/definitions/EdgeStorage" } } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "EdgeStorage" ] } }, "/cameras/{cameraId}/edgeStorages/{storageId}/recordingConfiguration": { "get": { "summary": "Get edge storage recording configuration", "description": "Get the recording configuration of the edge storage of the camera", "operationId": "getEdgeStorageRecordingConfiguration", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/storageId" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/EdgeRecordingConfiguration" } }, "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": [ "EdgeStorage" ] }, "patch": { "summary": "Update edge storage recording configuration", "description": "Update the recording configuration of the edge storage of the camera", "operationId": "updateEdgeStorageRecordingConfiguration", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/storageId" }, { "name": "EdgeRecordingConfiguration", "in": "body", "schema": { "$ref": "#/definitions/EdgeRecordingConfigurationUpdate" } } ], "responses": { "204": { "description": "No Content" }, "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": [ "EdgeStorage" ] } }, "/cameras/{cameraId}/edgeStorages/{storageId}/formatJobs": { "post": { "summary": "Format the edge storage location", "description": "Sends a request to the camera to format it's edge storage location identified by the storage id", "operationId": "formatEdgeStorage", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/storageId" } ], "responses": { "202": { "description": "Accepted - clients should listen for the STOMP notifications sent when the camera's edge storage status changes. When the edge storage 'state' field reaches a final status - i.e. Ready or Error - the formatting process can be considered finished." }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "EdgeStorage" ] } }, "/cameras/{cameraId}/edgeStorages/{storageId}/recordingSyncJobs": { "post": { "summary": "Starts a recording sync job", "description": "Starts a job which will sync the recordings from given time range from given storage location on the camera to the Cloud", "operationId": "startRecordingSyncJob", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/storageId" }, { "name": "RecordingSyncJob", "in": "body", "schema": { "$ref": "#/definitions/RecordingSyncJobParams" } } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/RecordingSyncJob" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "EdgeStorage" ] } } } }

swagger-edge-storage.yaml