Zones API

This is the API reference for zones.

{ "swagger": "2.0", "info": { "version": "2.1.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.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.", "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" ] }, "Address": { "type": "object", "properties": { "streetAddress": { "type": "string", "description": "The street address. For example, 1600 Amphitheatre Pkwy.", "maxLength": 64 }, "city": { "type": "string", "description": "City.", "maxLength": 32 }, "region": { "type": "string", "description": "Region such as state or province.", "maxLength": 32 }, "postalCode": { "type": "string", "description": "ZIP/Postal code.", "maxLength": 16 }, "country": { "type": "string", "pattern": "^$|^[a-zA-Z]{2}$", "description": "Country code as defined in ISO 3166-1 alpha-2." } } }, "ZoneStatus": { "type": "string", "description": "Status of the zone. Default value is CUSTOM.", "enum": [ "ARMED", "SILENT", "DISARMED", "PRIVATE", "CUSTOM" ] }, "Zone": { "type": "object", "properties": { "zoneId": { "type": "integer", "description": "Unique identifier for the zone." }, "name": { "type": "string", "minLength": 2, "maxLength": 32, "description": "Name the user has given to this zone." }, "accountId": { "type": "integer", "description": "ID of the account the Zone belongs to.", "minimum": 0 }, "address": { "$ref": "#/definitions/Address" }, "phone": { "type": "array", "description": "Phone number(s).", "maxLength": 2, "minLength": 0, "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "email": { "type": "string", "description": "E-mail address.", "minLength": 6, "maxLength": 128 }, "status": { "$ref": "#/definitions/ZoneStatus" }, "cameraIds": { "type": "array", "description": "IDs of the cameras belonging to this zone.", "minLength": 0, "items": { "type": "integer", "minimum": 0 } }, "cameras": { "type": "array", "description": "Embedded Camera objects of the cameras belonging to this zone.", "minLength": 0, "items": { "$ref": "#/definitions/Camera" } } }, "required": [ "zoneId", "name", "accountId", "address", "phone", "status" ] }, "ZoneOnUpdate": { "type": "object", "description": "Zone object on update.", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 32, "description": "Name the user has given to this zone." }, "address": { "$ref": "#/definitions/Address" }, "phone": { "type": "array", "description": "Phone number(s).", "maxItems": 2, "minItems": 0, "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "email": { "type": "string", "description": "E-mail address.", "minLength": 6, "maxLength": 128 }, "status": { "$ref": "#/definitions/ZoneStatus" } } }, "ZoneOnCreation": { "type": "object", "description": "Zone object on creation.", "properties": { "name": { "type": "string", "description": "Name the user has given to this zone.", "minLength": 2, "maxLength": 32 }, "address": { "$ref": "#/definitions/Address" }, "phone": { "type": "array", "description": "Phone number(s).", "maxLength": 2, "minLength": 0, "items": { "type": "string", "minLength": 1, "maxLength": 32 } }, "email": { "type": "string", "description": "E-mail address.", "minLength": 6, "maxLength": 128 }, "status": { "$ref": "#/definitions/ZoneStatus" } }, "required": [ "name" ] }, "Camera": { "type": "object", "properties": { "cameraId": { "type": "integer", "description": "Unique identifier for the camera." }, "name": { "type": "string", "minLength": 1, "maxLength": 32, "description": "Name the user has given to this camera." }, "deviceTypeId": { "type": "integer", "description": "ID of the device type" }, "ethMacAddress": { "type": "string", "description": "Mac-address of the device (Not to be confused with the wireless Mac-address)." }, "zoneId": { "type": "integer", "description": "ID of the zone where the camera is located." }, "accountId": { "type": "integer", "description": "ID of the owner of the camera." } }, "required": [ "cameraId", "name", "deviceTypeId", "zoneId", "accountId" ] } }, "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" } }, "unsupportedMediaType": { "description": "The requested resource does not understand the media type sent in the request.", "schema": { "$ref": "#/definitions/Error" } }, "conflict": { "description": "There was a conflict while trying to perform your request. Error detail will contain the detailed conflict.", "schema": { "$ref": "#/definitions/Error" } }, "internalServerError": { "description": "Something went wrong in the server. Please try again.", "schema": { "$ref": "#/definitions/Error" } } }, "parameters": { "zoneId": { "name": "zoneId", "in": "path", "description": "ID of the zone.", "required": true, "type": "integer" } }, "paths": { "/zones": { "get": { "summary": "Get the list of all zones the user has access to.", "description": "Retrieves the list of all zones the requesting user has access to. If the parameter accountId is provided, all the zones of that account is returned. Zones are returned as a list of Zone objects.", "operationId": "getZones", "parameters": [ { "name": "accountId", "in": "query", "description": "ID of the account of the desired zones.", "required": false, "type": "integer" }, { "name": "embedCameras", "in": "query", "description": "Boolean value indicating if the cameras objects must be embedded into the response instead of just the cameras IDs.", "required": false, "type": "boolean" } ], "responses": { "200": { "description": "OK", "schema": { "title": "Zones", "type": "array", "items": { "$ref": "#/definitions/Zone" } } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Zone" ] }, "post": { "summary": "Creates a new zone.", "description": "Creates a new zone for the requesting user. The body should not contain the zone ID, as it will be generated by the server during the creation of the zone. The newly created zone, with its ID, is returned in case of success.", "operationId": "addZone", "parameters": [ { "name": "zone", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ZoneOnCreation" } } ], "consumes": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/Zone" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "415": { "$ref": "#/responses/unsupportedMediaType" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Zone" ] } }, "/zones/{zoneId}": { "get": { "summary": "Get info of a specific zone.", "description": "Retrieves information of a specific zone.", "operationId": "getZone", "parameters": [ { "$ref": "#/parameters/zoneId" }, { "name": "embedCameras", "in": "query", "description": "Boolean value indicating if the cameras objects must be embedded into the response instead of just the cameras IDs.", "required": false, "type": "boolean" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/Zone" } }, "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": [ "Zone" ] }, "patch": { "summary": "Partially updates info of a specific zone.", "description": "Partially updates info of a specific zone. If a field is not set it will not be updated.", "operationId": "partialUpdateZone", "parameters": [ { "$ref": "#/parameters/zoneId" }, { "name": "zone", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ZoneOnUpdate" } } ], "consumes": [ "application/json" ], "responses": { "204": { "description": "OK" }, "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": [ "Zone" ] }, "put": { "summary": "Updates all the info of a specific zone.", "description": "Updates all the info of a specific zone. If a field is not set it is considered as set to null.", "operationId": "updateZone", "parameters": [ { "$ref": "#/parameters/zoneId" }, { "name": "zone", "in": "body", "required": true, "schema": { "$ref": "#/definitions/ZoneOnUpdate" } } ], "consumes": [ "application/json" ], "responses": { "204": { "description": "OK" }, "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": [ "Zone" ] }, "delete": { "summary": "Deletes a specific zone.", "description": "Deletes a specific zone from the system if there is no camera in the zone.", "operationId": "removeZone", "parameters": [ { "$ref": "#/parameters/zoneId" } ], "responses": { "204": { "description": "OK" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "description": "There was a conflict while trying to perform your request. Error code 5200 - This zone contains cameras or is the last zone and so it cannot be deleted.", "schema": { "$ref": "#/definitions/Error" } }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Zone" ] } }, "/zones/{zoneId}/cameras": { "get": { "summary": "Get cameras of a specific zone.", "description": "Retrieves a list of cameras of a specific zone. Only are returned the cameras that the user has access to.", "operationId": "getZoneCameras", "parameters": [ { "$ref": "#/parameters/zoneId" } ], "responses": { "200": { "description": "OK", "schema": { "title": "Cameras", "type": "array", "items": { "$ref": "#/definitions/Camera" } } }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Zone" ] } }, "/zones/{zoneId}/cameraIds": { "patch": { "summary": "Move cameras into the zone.", "description": "Move one or more cameras from other zone(s) into the zone given by zoneId.", "operationId": "moveZoneCameras", "parameters": [ { "$ref": "#/parameters/zoneId" }, { "name": "cameras", "description": "array of cameras to be moved to a common different zone.", "in": "body", "required": true, "schema": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "example": [ 1, 7, 1000, 56788 ] } } ], "consumes": [ "application/json" ], "responses": { "204": { "description": "OK" }, "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": [ "Zone" ] } }, "/cameras/{cameraId}/zone/{zoneId}": { "put": { "summary": "Updates the zone of a specific camera.", "description": "Updates the zone of a specific camera. The user must has specific permissions both to camera and zone.", "operationId": "moveCamerasToZone", "parameters": [ { "name": "cameraId", "in": "path", "description": "ID of the camera.", "required": true, "type": "integer" }, { "$ref": "#/parameters/zoneId" } ], "consumes": [ "application/json" ], "responses": { "204": { "description": "OK" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "Zone" ] } } } }
Camera Zone API YAML specification
swagger-zone.yaml