Camera snapshot API

The snapshot API allows the user to retrieve snapshots from their cameras. The Snapshot API is generating JPEG files on the fly based on the video stream. Because the file is generated it might take some time (up to 2 seconds) before the JPEG file is available. The CM Cloud can generate a limited number of JPEG images concurrently, if the limit is reached an error will be thrown.

It is mandatory to cache JPEG files locally on (mobile) devices and on your own infrastructure for a smooth user experience. Request a single JPEG file only once.

{ "swagger": "2.0", "info": { "version": "2.0.0", "title": "Cameramanager API - camera snapshot", "description": "RESTful API for the Cameramanager platform. APIs to get camera snapshot." }, "host": "rest.cameramanager.com", "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.", "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" ] } }, "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": "No permission to access the specified resource.", "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" } }, "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" }, "resolution": { "name": "resolution", "in": "query", "description": "Resolution of the snapshot.", "type": "string", "pattern": "^\\d+x\\d+$", "default": "320x240" } }, "paths": { "/cameras/{cameraId}/snapshot": { "get": { "summary": "Get the snapshot of the camera.", "description": "Retrieves the snapshot of a specific camera.", "operationId": "getCameraSnapshot", "parameters": [ { "$ref": "#/parameters/cameraId" }, { "$ref": "#/parameters/resolution" }, { "name": "timestamp", "in": "query", "description": "if present will look for the snapshot within a recording at the given time", "type": "string", "format": "date-time" } ], "produces": [ "image/jpeg", "application/json" ], "responses": { "200": { "description": "Returns the snapshot as a jpeg file.", "schema": { "type": "file" } }, "400": { "$ref": "#/responses/unsupportedCameraAction" }, "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": [ "Camera" ] } } } }
Camera Snapshot API YAML specification
swagger-camera-snapshot.yaml