User API

The User API allows the end-user to retrieve basic information about themselves such as their userId, accountId and names.

{ "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" ] }, "UserBaseUpdate": { "type": "object", "properties": { "email": { "type": "string", "description": "The email of the user.", "minLength": 5, "maxLength": 255 }, "firstName": { "type": "string", "description": "The first name of the user. Also known as \"Given Name\"", "minLength": 2, "maxLength": 32 }, "lastName": { "type": "string", "description": "The last name of the user. Also known as \"Family Name\".", "minLength": 2, "maxLength": 32 } } }, "UserBaseCreate": { "allOf": [ { "$ref": "#/definitions/UserBaseUpdate" }, { "type": "object", "properties": { "password": { "type": "string", "description": "Optional user password" }, "startWithZeroRights": { "type": "boolean", "default": false, "description": "Optional flag indicating if all the rights for the newly created user should be revoked. Default it is set to 'false' which means that the rights will be copied from the user that triggers the api call." } } } ], "required": [ "email", "firstName", "lastName" ] }, "UserBase": { "allOf": [ { "$ref": "#/definitions/UserBaseUpdate" }, { "type": "object", "properties": { "userId": { "type": "integer", "description": "The user ID of the user." }, "accountId": { "type": "integer", "description": "The account ID of the account the user belongs to." } } } ], "required": [ "userId", "accountId", "email", "firstName", "lastName" ] } }, "parameters": { "userId": { "name": "userId", "in": "path", "description": "ID of the user.", "required": true, "type": "integer" } }, "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" } }, "internalServerError": { "description": "Something went wrong in the server. Please try again.", "schema": { "$ref": "#/definitions/Error" } }, "conflict": { "description": "There was a conflict while trying to perform your request. See error details for more information." } }, "paths": { "/users": { "get": { "summary": "Get a list of all users the user has access to.", "description": "Retrieves a list of all users the requesting user has access to. Each element from the list contains basic information about the user like userId, accountId, email, firstName, lastName.", "operationId": "getUsers", "responses": { "200": { "description": "OK", "schema": { "title": "Users", "type": "array", "items": { "$ref": "#/definitions/UserBase" } } }, "401": { "$ref": "#/responses/unauthorized" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "User Base" ] }, "post": { "summary": "Create a new user.", "description": "Create a new user for the requesting users account.", "operationId": "addBaseUser", "parameters": [ { "name": "user", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UserBaseCreate" } } ], "consumes": [ "application/json" ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/UserBase" } }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "User Base" ] } }, "/users/self": { "get": { "summary": "Get basic information about the current user.", "description": "Get basic information about the current user like userId, accountId, email, firstName, lastName of the user.", "operationId": "getBaseUser", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/UserBase" } }, "401": { "$ref": "#/responses/unauthorized" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "User Base" ] }, "patch": { "summary": "Update basic information about the current user.", "description": "Update user basic information like email, first and last name.", "operationId": "updateBaseUser", "parameters": [ { "name": "UserBaseUpdate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UserBaseUpdate" } } ], "responses": { "204": { "description": "No content" }, "400": { "$ref": "#/responses/validationError" }, "401": { "$ref": "#/responses/unauthorized" }, "403": { "$ref": "#/responses/forbidden" }, "406": { "$ref": "#/responses/notAcceptableError" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "User Base" ] } }, "/users/{userId}": { "get": { "summary": "Get basic information about a specific user.", "description": "Get basic information about a specific user like userId, accountId, email, firstName, lastName.", "operationId": "getBaseUserById", "parameters": [ { "$ref": "#/parameters/userId" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/UserBase" } }, "401": { "$ref": "#/responses/unauthorized" }, "404": { "$ref": "#/responses/resourceNotFound" }, "406": { "$ref": "#/responses/notAcceptableError" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "User Base" ] }, "patch": { "summary": "Update basic information about a specific user.", "description": "Update user basic information like email, first and last name of a specific user.", "operationId": "updateBaseUserById", "parameters": [ { "$ref": "#/parameters/userId" }, { "name": "UserBaseUpdate", "in": "body", "required": true, "schema": { "$ref": "#/definitions/UserBaseUpdate" } } ], "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" }, "409": { "$ref": "#/responses/conflict" }, "500": { "$ref": "#/responses/internalServerError" } }, "tags": [ "User Base" ] }, "delete": { "summary": "Delete a specific user.", "description": "Delete a specific user from the system.", "operationId": "deleteBaseUser", "parameters": [ { "$ref": "#/parameters/userId" }, { "name": "password", "in": "query", "description": "Password of the user who requests the delete operation. When deleting a user this field allows the client to ask the current user for the password to confirm that he is really sure about this destructive action.", "required": false, "type": "string" } ], "responses": { "204": { "description": "OK" }, "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": [ "User Base" ] } } } }

swagger-user-base.yaml