Skip to main content

mDNS-SD Configuration API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

warning

This API is in BETA stage. The API is provided for testing purposes and is subject to backward-incompatible changes, including modifications to functionality, behavior, and availability. Please don't use in production environment.

Overview​

The mDNS-SD configuration API makes it possible to enable and disable the mDNS-SD (Multicast DNS Service Discovery) functionality, set and get the friendly name of a device, and make Discovery calls to find other devices on the local network.

Use cases​

Manage mDNS-SD​

Enable or disable mDNS-SD​

Set the mdnssd.v2beta.enabled property to enable or disable mDNS-SD.

Example:

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2beta/enabled \
  --data '{
    "data": true
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Manage friendly name​

Use mdnssd.v2beta.friendlyName to check or change the friendly name.

Example:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2beta/friendlyName
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": "AXIS M1075-L - B8A44FE56631"
}
curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2beta/friendlyName \
  --data '{
    "data": "string"
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Make discovery call​

Make a discovery call to look for nearby devices with specific services.

This trigger will check for other mDNS-SD clients on the local network with services supplied in the services parameter. If multiple services are supplied, any client advertising any of the services will be discovered.

Example:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2beta/discovery \
  --data '{
    "data": {
        "services": [
            "_axis-video._tcp"
        ],
        "timeout": 2
    }
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "deviceServices": [
                {
                    "serviceName": "_axis-video._tcp",
                    "servicePort": 80,
                    "serviceTxt": "macaddress=B8A44F1D58C3"
                }
            ],
            "friendlyName": "AXIS Q3536-LVE - B8A44F1D58C3",
            "hostname": "spechn-3.local.",
            "interface": "eth0",
            "ipv4Address": [
                "192.168.0.218"
            ],
            "ipv6Address": [
                "ccee:2da0:54ac:8a2f:baa4:4fff:fe1d:58c3",
                "fe80::baa4:4fff:fe1d:58c3"
            ]
        }
    ]
}

Custom errors​

Error codeError messageDescription
100Invalid requestmDNS-SD is disabled during a discovery call.

Example:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2beta/discovery \
  --data '{
    "data": {
        "services": [
            "_axis-video._tcp"
        ],
        "timeout": 2
    }
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "error",
    "error": {
        "code": 100,
        "message": "Backend defined error: \"mDNS-SD is not enabled, can not call discovery.\""
    }
}

API definition​

Structure​

mdnssd.v2 (Root Entity)
    ├── enabled (Property)
    ├── friendlyName (Property)
    ├── discovery (Action)

Entities​

mdnssd.v2​

  • Description: mDNS-SD configuration.
  • Type: Singleton
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No
Properties​
enabled​
  • Description: The enabled state for mDNS-SD.
  • Datatype: boolean
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
friendlyName​
  • Description: The friendly name for mDNS-SD.
  • Datatype: string
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​
discovery​
  • Description: Discover devices in the network.
  • Request Datatype: DiscoveryData
  • Response Datatype: DiscoveryResponseData
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No

Data Types​

Device​

  • Description: Device found by discovery.
  • Type: complex
  • Fields
    • deviceServices
      • Description: The services this device offers.
      • Type: DeviceServiceList
      • Nullable: No / Gettable: Yes
    • friendlyName
      • Description: The friendlyname of the device.
      • Type: string
      • Nullable: No / Gettable: Yes
    • hostname
      • Description: The hostname of the device.
      • Type: string
      • Nullable: No / Gettable: Yes
    • interface
      • Description: On which local interface the device was discovered.
      • Type: string
      • Nullable: No / Gettable: Yes
    • ipv4Address
      • Description: A list of IPv4 addresses found on the device.
      • Type: StringArray
      • Nullable: No / Gettable: Yes
    • ipv6Address
      • Description: A list of IPv6 addresses found on the device.
      • Type: StringArray
      • Nullable: No / Gettable: Yes

DeviceService​

  • Description: A service which a discovered device offers.
  • Type: complex
  • Fields
    • serviceName
      • Description: The name of the service.
      • Type: string
      • Nullable: No / Gettable: Yes
    • servicePort
      • Description: The port on which the service may be found.
      • Type: integer
      • Nullable: No / Gettable: Yes
    • serviceTxt
      • Description: The text record of the service.
      • Type: string
      • Nullable: No / Gettable: Yes

DeviceServiceList​

  • Description: A list of DeviceServices.
  • Type: array
  • Element type: DeviceService
  • Null Value: No

DiscoveryData​

  • Description: Data type used for discovery.
  • Type: complex
  • Fields
    • services
      • Description: The services to look for during the discovery.
      • Type: ServiceList
      • Nullable: No / Gettable: Yes
    • timeout
      • Description: The timeout for how many seconds a discovery should last.
      • Type: Timeout
      • Nullable: No / Gettable: Yes

DiscoveryResponseData​

  • Description: Devices found through discovery.
  • Type: array
  • Element type: Device
  • Null Value: No

Service​

  • Description: A service for the discovery to discover.
  • Type: string
  • Pattern: ^_[A-Za-z0-9]A-Za-z0-9-_]{0,13}[A-Za-z0-9]\._(udp|tcp)$|^_[A-Za-z0-9]\.\_(udp|tcp)$

ServiceList​

  • Description: A list of services.
  • Type: array
  • Element type: Service
  • Null Value: No

StringArray​

  • Description: An array of strings.
  • Type: array
  • Element type: string
  • Null Value: No

Timeout​

  • Description: Valid timeout value in seconds.
  • Type: integer
  • Minimum Value: 1
  • Maximum Value: 15
Last updated on