Basic device information

Description

AXIS Basic device information API can be used to retrieve simple information about the product. This information is used to identify basic properties of the product, and is based around the following methods:

Method	Usage
`getProperties`	Get a list of requested parameter values.
`getAllProperties`	Get a list of all supported parameters.
`getAllUnrestrictedProperties`	Get a list of all unrestricted parameters.
`getSupportedVersions`	Get a list of supported API versions.

The API consists of an authenticated CGI which should be called using the HTTP POST method and JSON formatted data as an input. Using the API makes it possible to:

Get all supported properties in one shot.
Get a selected subset of properties.
Get all unrestricted properties.
Get a list of supported API versions.

Identification

Firmware: 8.40 and later
API Discovery: id=basic-device-info
Property: BasicDeviceInfo.BasicDeviceInfo="yes"

Common examples

Get basic device information

Use this example to receive information on how to identify and communicate with a device before it is configured/initialized in its internal state, or to identify the way how to communicate with the device.

Basic device information (BDI) service will provide some information about the device that will make it easier to identify. For example, on some low-end products where Parameter management isn’t available, this service will be an entry point to identify the device.

All requests to the BDI service is done by following this HTTP request with a proper JSON body. Responses to the API calls will also be delivered as JSON data.

http://myserver/axis-cgi/basicdeviceinfo.cgi

Get all properties

1) Request all properties with the following JSON request:

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getAllProperties"
}

2) Parse the JSON response to include all properties:

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "data": {
  "propertyList": {
      "Archtecture": "mips",
      "Brand": "AXIS",
      "BuildDate": "Feb 14 2018 13:08",
      "HardwareID": "714.4",
      "ProdFullName": "AXIS Q3505 Mk II Fixed Dome Network Camera",
      "ProdNbr": "Q3505 Mk II",
      "ProdShortName": "AXIS Q3505 Mk II",
      "ProdType": "Network Camera",
      "ProdVariant": "",
      "SerialNumber": "ACCC8E78B977",
      "Soc": "Axis Artpec-5",
      "SocSerialNumber": "00000000-00000000-44123C08-C840037D",
      "Version": "8.20.1",
      "WebURL": "http://www.axis.com"
    }
  }
}

Get some properties

1) Request a subset of the properties with the following JSON request.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getProperties",
  "params": {
    "propertyList": [
      "Brand",
      "ProdNbr",
      "Version"
    ]
  }
}

2) Parse the JSON response which includes selected properties.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "data": {
    "propertyList": {
      "Brand": "AXIS",
      "ProdNbr": "Q3505 Mk II",
      "Version": "8.20.1",
    }
  }
}

Handle errors

If an error occur while processing the clients request a JSON response will be returned containing an error code and a detailed message.

1) Request properties that does not exist with the following JSON request.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getProperties",
  "params": {
    "propertyList": [
      "Brand",
      "ProdNbr",
      "Version",
      "invalid_property_name"
    ]
  }
}

2) Parse the JSON response which includes an error message and a message.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "error": {
    "code": 1000,
    "message": "Property not supported: invalid_property_name"
  }
}

Get basic device information as an anonymous user

Use this example to show some device information during the initial access before a root user has been defined, or when no user is logged in.

http://myserver/axis-cgi/basicdeviceinfo.cgi

Get all unrestricted properties

1. Request all unrestricted properties using the following JSON request:

{
  "apiVersion": "1.2",
  "context": "Client defined request ID",
  "method": "getAllUnrestrictedProperties"
}

2. Parse the JSON response.

{
  "apiVersion": "1.2",
  "context": "Client defined request ID",
  "data": {
    "propertyList": {
      "Brand": "AXIS",
      "BuildDate": "Aug 04 2020 11:15",
      "HardwareID": "75E.1",
      "ProdFullName": "AXIS Q1785-LE Network Camera",
      "ProdNbr": "Q1785-LE",
      "ProdShortName": "AXIS Q1785-LE",
      "ProdType": "Network Camera",
      "ProdVariant": "",
      "SerialNumber": "ACCC8EAF8C30",
      "Version": "8.20.1",
      "WebURL": "http://www.axis.com"
    }
  }
}

Handle errors

If an error occur while processing the clients request a JSON response will be returned containing an error code and a detailed message.

See Get basic device information for an example and Error handling for general error guidelines.

API specification

getAllProperties

getAllProperties is used to retrieve all properties provided by the BDI service. This API can also be used to identify what type of properties BDI service is providing.

Request

Security level: Operator
Method: POST

http://<servername>/axis-cgi/basicdeviceinfo.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": "<string>",
  "method": "getAllProperties"
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>`	Optional. Client sets this value and the server echoes the data back in the response. If set, it will be present in the response regardless of whether the response is successful or not.
`method="getAllProperties"`	Required. Specifies that the `getAllProperties` operation is performed.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": "<string>",
  "data": {
    "propertyList": {
      "Architecture": "<string>",
      "Brand": "<string>",
      "BuildDate": "<string>",
      "HardwareID": "<string>",
      "ProdFullName": "<string>",
      "ProdNbr": "<string>",
      "ProdShortName": "<string>",
      "ProdType": "<string>",
      "ProdVariant": "<string>",
      "SerialNumber": "<string>",
      "Soc": "<string>",
      "SocSerialNumber": "<string>",
      "Version": "<string>",
      "WebURL": "<string>"
    }
  }
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>`	Text string echoed back if it has been provided by the client in the corresponding request.
`data.propertyList`	Contains all property pairs for the device the service is running on. All available properties are included in the response.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

No specific failure exists for this method. General errors are listed in Error handling.

getProperties

getProperties is used to retrieve a subset of the properties provided by the BDI service.

Request

Security level: Operator
Method: POST

http://<servername>/axis-cgi/basicdeviceinfo.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": "<string>",
  "method": "getProperties",
  "params": {
    "propertyList": [
      "<property1>",
      "<property2>",
      "<property3>",
      ...
    ]
  }
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>`	Optional. Client sets this value and the server echoes the data back in the response. If set, it will be present in the response regardless of whether the response is successful or not.
`method="getProperties"`	Required. Specifies that the `getProperties` operation is performed.
`params.propertyList=<array of property names>`	Required. Specifies which properties should be returned with the response. If this field is empty an empty list will be returned.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": "<string>",
  "data": {
    "propertyList": {
      "<property1>": "<string>",
      "<property2>": "<string>",
      "<property3>": "<string>",
      ...
    }
  }
}

Parameter	Description
`apiVersion`	The API version that is used.
`context=<string>`	Text string echoed back if it is provided by the client in the corresponding request.
`data.propertyList`	Contains selected property pairs for the device on which the service is running on.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

No specific failure exists for this method. General errors are listed in Error handling.

getAllUnrestrictedProperties

getAllUnrestrictedProperties is used to retrieve all unspecified properties by the BDI service.

Request

Security level: Anonymous
Method: POST

http://<servername>/axis-cgi/basicdeviceinfo.cgi

{
  "apiVersion": "<Major>.<Minor>",
  "context": "<string>",
  "method": "getAllUnrestrictedProperties"
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>`	Optional. Client sets this value and the server echoes the data back in the response. If set, it will be present in the response regardless of whether the response is successful or not.
`method="getAllUnrestrictedProperties"`	Required. Specifies that the `getAllUnrestrictedProperties` operation is performed.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": "<string>",
  "data": {
    "propertyList": {
      "Brand": "<string>",
      "BuildDate": "<string>",
      "HardwareID": "<string>",
      "ProdFullName": "<string>",
      "ProdNbr": "<string>",
      "ProdShortName": "<string>",
      "ProdType": "<string>",
      "ProdVariant": "<string>",
      "SerialNumber": "<string>",
      "Version": "<string>",
      "WebURL": "<string>"
    }
  }
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>`	Text string echoed back if it has been provided by the client in the corresponding request.
`data.propertyList`	Contains all property pairs for the device the service is running on. All available properties are included in the response.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

No specific failure exists for this method. General errors are listed in Error handling.

getSupportedVersions

getSupportedVersions is used to retrieve supported API versions.

Request

Security level: Anonymous
Method: POST

http://<servername>/axis-cgi/basicdeviceinfo.cgi

{
  "context": <string>,
  "method": "getSupportedVersions"
}

Parameter	Description
`context=<string>`	Optional. The client sets this value and the server echoes the data back in the response. If set, it will be present in the response regardless of whether the response is successful or not.
`method="getSupportedVersions"`	Required. Specifies that the `getSupportedVersions` operation can be performed.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["<Major>.<Minor1>", "<Major2>.<Minor2>"]
  }
}

Parameter	Description
`context=<string>`	Text string echoed back if it is provided by the client in the corresponding request.
`method="getSupportedVersions"`	Required. Specifies that the `getParameters` operation is performed.
`data.apiVersions`	Contains an array of supported versions.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

No specific failure exists for this method. General errors are listed in Error handling.

Error handling

The following table lists general errors that may occur for any JSON request. Errors that are specific for a method are listed under the API description for that method. Descriptions are only used to describe the type of the error code. Detailed information on the fault will be provided in a message field inside the error structure.

Code	Description
`1000`	Invalid parameter with the value specified.
`2001`	Access forbidden.
`2002`	HTTP request types are not supported. Only POST is supported.
`2003`	The requested API version is not supported.
`2004`	The method is not supported.
`4000`	Invalid JSON format.
`4002`	Required parameter is either missing or invalid.
`8000`	Internal error. Refer to the message field or logs.

All failures are returned with the following JSON response:

Error response body syntax

{
  "apiVersions": "<Major>.<Minor>",
  "context": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Parameter	Description
`apiVersion`	The API version that is used.
`context=<string>`	Text string echoed back if it is provided by the client in the corresponding request.
`error.code`	Contains an error code. This value can be a method specific or a general error code.
`error.message`	Contains a detailed message about the occurred failure.