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 

  1. Call the API 
  2. Wait for response, the timeout for this call is 180 secs ( it takes around 3 mins for the camera to come online ) 
  3. Parse the response 
  4. 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
    1. added - Camera added successfully 
    2. failure - Camera not added successfully and the reason for this failure will be in the SubStatus
    3. inProgress - Used internally, you will not get this status, but if you get it treat it as a failure
    4. validated-  Used internally, you will not get this status but if you get it treat it as a failure
  5. 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 Error Message
    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.
    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.
    failedAddingDeviceAfterValidation The device was validated successfully, but an unexpected error occurred afterward. Please try again later.
    hwIdRegistrationFailed The device is already added to an account, please remove the device from the current account before adding it to a new account.
    unsupportedModel The device is not supported, you can only add supported models to the account.
    localUrlValidationFailed Problem detected with your device. Please restart or factory reset the device.
    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.
    deviceIdentificationFailed Something went wrong. The device could not be identified. Please restart or factory reset the device and try again.
    Other Something went wrong. Please try again later or 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.