mDNS-SD API

The methods of this API are accessible through mdnssd.cgi, which should be called using HTTP POST with JSON formatted data as its input. The API consists of the following methods, each representing a single functionality:

• getMdnssdInfo

• getSupportedVersions

• setMdnssdConfiguration

• discover

An API call includes the API version, a context (optional), a method and its input parameters. The only exception to this rule is the method getSupportedVersions, where the API version is optional.

getMdnssdInfo

getSupportedVersions

setMdnssdConfiguration

discover

API Discovery

id=mdnssd

For information about the API Discovery, see API Discovery service

This API renders the process of setting and retrieving mDNS-SD related parameters through param.cgi obsolete, however, the following parameters are still in use and fully supported by the mdnssd.cgi:

• Network.Bonjour.Enabled

• Network.Bonjour.FriendlyName

Using either cgi on devices that have both the mdnssd.cgi and param.cgi will yield the same result.

Use this example to configure the Axis device to be discoverable on a local network by using mDNS-SD.

1) Navigate to the mDNS-SD configuration page in the Video Management System (VMS). This triggers the VMS to retrieve the mDNS-SD configuration from the device and then present it.

POST http://<device-address>/axis-cgi/mdnssd.cgi HTTP/1.1
Content-type: application/json
Content-length: <size of JSON input parameters below>

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getMdnssdInfo"
}

2) The VMS parses the response and if the request is successful it will be presented on the mDNS-SD page.

a) Successful response.

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getMdnssdInfo",
  "data": {
    "enabled": true,
    "friendlyName": "AXIS P1234 - 00408C1A2B3C"
  }
}

b) Error response. This error occurs if the CGI encounters an internal error that causes it to abort the operation.

{
  "apiVersion": "1.0",
  "context": "abc",
  "error": {
    "code": 1000,
    "message": "Internal error"
  }
}

3) Read the returned information and make the necessary changes, then instruct the VMS to apply the new configurations with the request described below.

POST http://<device-address>/axis-cgi/mdnssd.cgi HTTP/1.1
Content-type: application/json
Content-length: <size of JSON input parameters below>

JSON input parameters

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setMdnssdConfiguration",
  "params": {
    "enabled": true,
    "friendlyName": "Kitchen camera"
  }
}

4) The VMS will receive a response and, depending on its success, returns a result of the operation.

a) Successful response.

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setMdnssdConfiguration",
  "data": {}
}

b) Error response 1: When the VMS has sent an incomplete request and misses at least one required parameter.

{
  "apiVersion": "1.0",
  "context": "abc",
  "error": {
    "code": 4003,
    "message": "Missing parameter(s)"
  }
}

c) Error response 2: When the error Invalid parameter(s) (4004), which also contains a subCode, that describes which parameter that was deemed invalid. For a list of possible sub codes, see the mDNS-SD invalid parameter error sub codes table below.

{
  "apiVersion": "1.0",
  "context": "abc",
  "error": {
    "code": 4004,
    "message": "Invalid parameter(s)",
    "details": {
      "subCode": 2
    }
  }
}

For further instructions, see getMdnssdInfo.

For further instructions, see setMdnssdConfiguration.

Use this example to receive information on which API versions the VMS can use when it is communicating with an Axis device.

Get a list of supported API versions

1) Navigate to the device management page to add an Axis device. The VMS will receive the device address and make an API call to get a list of supported API versions, it decides if it can operate the device and presents you with further options.

POST http://<device-address>/axis-cgi/mdnssd.cgi HTTP/1.1
Content-type: application/json
Content-length: <size of JSON input parameters below>

JSON input parameters

{
  "context": "abc",
  "method": "getSupportedVersions"
}

2) The VMS will parse the response and if the request is successful, it will present the appropriate choices on the management page.

a) Successful response.

{
  "apiVersion": "3.1",
  "context": "abc",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": [
      "1.0",
      "2.4",
      "3.1"
    ]
  }
}

b) Error response. This error will occur if the CGI encounters an internal error that causes it to abort the operation.

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "getSupportedVersions",
  "error": {
    "code": 1000,
    "message": "Internal error"
  }
}

See getSupportedVersions for further instructions.

Use this example to discover other devices and their respective service offerings on the network.

Discover devices exposing the video services

1. Navigate to the device management page to add an Axis device. The VMS will receive the device address and make an API call to get a list of supported API versions, it decides if it can operate the device and presents you with further options.

POST http://<device-address>/axis-cgi/mdnssd.cgi HTTP/1.1
Content-type: application/json
Content-length: <size of JSON input parameters below>

{
  "apiVersion": "1.1",
  "context": "abc",
  "method": discover",
  "params": {
    "services": ["_axis-video._tcp"],
    "timeout": 5
  }
}

2. The VMS will parse the response and if the request is successful, it will present the appropriate choices on the management page.

{
  "apiVersion": "1.1",
  "context": "abc",
  "method": "discover",
  "data": {
    "devices": [
      {
        "friendlyName": "device-1",
        "hostname": "axis-abc",
        "interface": "eth0",
        "ipv4Addresses": ["192.168.0.91", "160.254.0.1"],
        "ipv6Addresses": [],
        "services": [
          {
            "name": "_axis-video._tcp",
            "port": 80,
            "txt": "macaddress:abcdefghijk"
          }
        ]
      },
      {
        "friendlyName": "device-2"
        "hostname": "axis-abd",
        "interface": "eth0",
        "ipv4Addresses": ["192.168.0.92", "160.254.0.2"],
        "ipv6Addresses": [],
        "services": [
          {
            "name": "_axis-video._tcp",
            "port": 80,
            "txt": "macaddress:abcdefghijl"
          }
        ]
      }
    ]
  }
}

{
  "apiVersion": "1.1",
  "context": "abc",
  "method": "discover",
  "error": {
    "code": 1000,
    "message": "Internal error"
  }
}

API reference

See discover for additional information.

Returns the mDNS-SD service configuration on an Axis device.

Request

Security level

Administrator

Method

POST

Content-type

application/json

http://<device-address>/axis-cgi/mdnssd.cgi

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getMdnssdInfo",
  "params": {}
}

Return value - Success

Returns the mDNS-SD service configuration on the Axis device.

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getMdnssdInfo",
  "data": {
    "enabled": <boolean>,
    "friendlyName": <string>
  }
}

Return value - Error

Returns an error code and a description.

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getMdnssdInfo",
  "error": {
    "code": <error code>,
    "message": <string>
  }
}

Error codes

See General error codes.

Retrieves a list on supported API versions.

Request

Security level

Administrator

Method

POST

Content-type

application/json

http://<device-address>/axis-cgi/mdnssd.cgi

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

Return value - Success

Returns a list of supported API versions.

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": [<string>]
  }
}

Return value - Error

Returns an error code and a description.

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "getSupportedVersions",
  "error": {
    "code": <integer>,
    "message": <string>
  }
}

Error codes

See General error codes.

Sets the mDNS-SD service configuration on an Axis device.

Request

Security level

Administrator

Method

POST

http://<device-address>/axis-cgi/mdnssd.cgi

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "setMdnssdConfiguration",
  "params": {
    "enabled": <boolean>,
    "friendlyName": <string>
  }
}

Return value - Success

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "setMdnssdConfiguration",
  "data": {}
}

Return value - Error

Returns an error code and a description.

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "setMdnssdConfiguration",
  "error": {
    "code": <error code>,
    "message": <string>
    "details": {
      "subCode": <error sub code>
    }
  }
}

Error codes

See General error codes.

Returns on-demand discoveries of specified mDNS-SD services on the network after a specified timer has run out.

Request

Security level

Administrator

Method

POST

http://<device-address>/axis-cgi/mdnssd.cgi

{
  "apiVersion": "<major>.<minor>",
  "context": <string>,
  "method": "discover",
  "params": {
    "services": [<string>],
    "timeout": <integer>
  }
}

Return value - Success

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "discover",
  "data": {
    "devices": [
      {
        "friendlyName": <string>,
        "hostname": <string>,
        "interface": <string>,
        "ipv4Addresses": [<string>],
        "ipv6Addresses": [<string>,]
        "services": [
          {
            "name": <string>,
            "port": <integer>,
            "txt": <string>
          }
        ]
      }
    ]
  }
}

Return value - Error

Returns an error code and a description.

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": <major>.<minor>,
  "context": <string>,
  "method": "discover",
  "error": {
    "code": <error code>,
    "message": <string>
    "details": {
      "subCode": <error sub code>
    }
  }
}

Error codes

See General error codes.

These error codes are common for all API methods.

In the event of an internal CGI error (1000) the HTTP response code will be 500, while the other CGI errors are set to 200.

Note that the user authentication and authorization of the CGI is performed on a HTTP level and will return the HTTP error code 401 if the authentication is unsuccessful. The authorization of the CGI is performed after the HTTP authentication and authorization has passed, and will always return a HTTP code 200 regardless of the result. If it fails at a latter stage, the response will consist of a 200 HTTP code and JSON data containing the error 4002, meaning that the authorization failed and that the CGI was not authorized to use some of the resources it needed to accomplish its task.