Adding Camera via the API

Goal

The goal of this guide is to explain how the "Add Camera" process works and how API users should implement it. Adding a camera in CameraManager is a two-step process and the user needs to call two APIs to find out if the camera is correctly added or not.

Assumptions

Reader has a CameraManager account
Reader has a CameraManager compatible camera
Reader is familiar with getting data from a REST API
Reader is familiar with JSON data structures for implementing the REST API

Process

Adding a camera to CameraManager account is a 2 step process

Step 1: You add the camera to the account using the Cameras API. Getting success from this doesn't mean that the camera is added successfully, it means that the add camera process has been started successfully.

Step 2: After you get success from the above API, you need to call Add Camera Status Poll API (only once, you don't have to call it regularly) to get the status of the add camera process. The way to call the Add Camera Status Poll API is as follows

Call the API
Wait for response, the timeout for this call is 180 secs ( it takes around 3 mins for the camera to come online )
Parse the response
The response will have a property called Status which can have 4 values (inProgress, validated, added, failure), steps to be taken for each value of Status
- added - Camera added successfully
- failure - Camera not added successfully and the reason for this failure will be in the SubStatus
- inProgress - Used internally, you will not get this status, but if you get it treat it as a failure
- validated- Used internally, you will not get this status but if you get it treat it as a failure
If you don't get added as the Status then you need to parse the SubStatus property to get the reason for the failure, below is a list of error messages you can show based on the SubStatus, this is just indicative and you are free to choose your own error messages, the meaning for each error is defined API definition page.

SubStatus	ErrorMessage
unsupportedModel	The device is not supported, you can only add supported models to the account.
Other	Something went wrong. Please try again later or contact support.
notOnline	The device wasn't able to connect to the cloud. Please make sure the device is connected to a power source and has a stable internet connection.
notConnected	The device wasn't able to connect to the cloud. Please make sure the device is connected to a power source and has a stable internet connection.
localUrlValidationFailed	Problem detected with your device. Please restart or factory reset the device.
hwIdRegistrationFailed	The device is already added to an account, please remove the device from the current account before adding it to a new account.
failedAddingDeviceAfterValidation	The device was validated successfully, but an unexpected error occurred afterward. Please try again later.
deviceIdentificationFailed	Something went wrong. The device could not be identified. Please restart or factory reset the device and try again.
credentialValidationFailed	The device doesn't have the default credentials. Please factory reset your device or make sure your device has the default credentials. Try again after this.
credentialSetupFailed	Unknown error. The application has encountered an unknown error, try again later. If the problem persists, contact support.

Based on the Status and SubStatus the user should have clarity what are the next steps if the Adding of the camera fails.