Video summary API

{ "swagger": "2.0", "info": { "version": "2.0.0", "title": "Cameramanager API", "description": "RESTful API for the Eagle Eye CameraManager platform. APIs related to camera video summaries." }, "host": "", "schemes": [ "http", "https" ], "basePath": "/rest/v2.0", "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:\n * request the camera to generate a summary using available snapshots", "type": "string", "enum": [ "" ] }, "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." }, "CameraVideoSummaryRequest": { "type": "object", "description": "The parameters used to generate the video summary for a camera.", "properties": { "minTimestamp": { "type": "string", "format": "date-time", "description": "The start time of the window of snapshots used for the video summary. Defaults to current timestamp minus 24 hours." }, "maxTimestamp": { "type": "string", "format": "date-time", "description": "The end time of the window of snapshots used for the video summary. Defaults to current timestamp." } } }, "VideoSummaryCameraJob": { "allOf": [ { "$ref": "#/definitions/CameraJob" }, { "type": "object", "properties": { "statusDetails": { "$ref": "#/definitions/VideoSummaryCameraJobStatusDetails" }, "jobDetails": { "$ref": "#/definitions/VideoSummaryCameraJobDetails" } } } ] }, "VideoSummaryCameraJobStatusDetails": { "description": "Currently Video Summary jobs do not provide any status information while the job is running.", "allOf": [ { "$ref": "#/definitions/CameraJobStatusDetails" } ] }, "VideoSummaryCameraJobDetails": { "allOf": [ { "$ref": "#/definitions/CameraJobDetails" }, { "type": "object", "properties": { "minTimestamp": { "type": "string", "format": "date-time", "description": "The start time of the window of snapshots used for the video summary." }, "maxTimestamp": { "type": "string", "format": "date-time", "description": "The end time of the window of snapshots used for the video summarry." } } } ], "required": [ "minTimestamp", "maxTimestamp" ] } }, "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" } }, "overloadedServerError": { "description": "The server is currently busy and cannot process 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" }, "jobId": { "name": "jobId", "in": "path", "description": "ID of the job, for example \"R-490753-d6eec9c8\"", "required": true, "type": "string", "pattern": "[-0-9a-f]", "minLength": 8, "maxLength": 32 }, "cameraVideoSummaryRequest": { "name": "CameraVideoSummaryRequest", "description": "(Optional) Window from which snapshots are used to generate the daily video summary. When no window is specified, the available snapshots of the last 24 hours are used.\n", "in": "body", "required": false, "schema": { "$ref": "#/definitions/CameraVideoSummaryRequest" } } }, "paths": { "/cameras/{cameraId}/summary": { "post": { "summary": "Trigger the generation of a video summary.", "description": "Start the generation of the video summary, so it can be retrieved later using the returned job ID. A video summary is generated using the smart detection snapshots within the time period. The API will use all available snapshots to generate a video, however, when too many snapshots are available, an uniformly interleaved selection of the available snapshots is chosen to generate the video. When the number of snapshots is low, the speed and length of the video will gradually decrease. No video summary will be generated when there are only very few snapshots available.\n", "operationId": "startVideoSummaryGeneration", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/cameraVideoSummaryRequest" } ], "responses": { "202": { "description": "Accepted", "schema": { "$ref": "#/definitions/VideoSummaryCameraJob" } }, "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" }, "503": { "$ref": "#/responses/overloadedServerError" } }, "tags": [ "VideoSummary" ] } }, "/cameras/{cameraId}/summary/{jobId}.mp4": { "get": { "summary": "Retrieve the video summary mp4 file by job ID.", "description": "Get the mp4 file containing the daily video summary identified by the job ID. The file will only be available when the job is finished, which can be checked using the Jobs API.\n", "operationId": "getGeneratedVideoSummaryByJobId", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/jobId" } ], "produces": [ "video/mp4", "application/json" ], "responses": { "200": { "description": "OK", "schema": { "type": "file" } }, "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": [ "VideoSummary" ] } } } }