Introduction

The following abbreviations are used throughout the VAPIX® documentation.

CGI

Common Gateway Interface – a standardized method of communication between a client (for example a web browser) and a server (for example a web server).

TBD

To be done/designed – signifies that the referenced section/subsection/entity is intended to be specified, but has not reached a level of maturity to be public at this time.

N/A

Not applicable - the feature/parameter/value is of no use in a specific task.

URL

A Uniform Resource Location (URL) is a compact string representation for a resource available via the Internet. RFC 1738 describes the syntax and semantics for a URL.

URI

A Uniform Resource Identifier (URI) is a compact string of characters for identifying an abstract or physical resource. RFC 3986 describes the generic syntax of URI.

Obsolete

Removed

The Axis product returns standard HTTP status codes. See RFC 1945 and RFC 2616.

HTTP and RTSP VAPIX requests must follow the URI generic syntax defined in RFC 3986. Use character encoding ISO/IEC 8859-1. If a parameter in the request contains characters that are not allowed in a URI, these characters must be percent-encoded. That is, characters such as /, \, :, =, &, ?, etc in a <argument> or a <value> must be replaced by %<ASCII hex>.

http://<servername>/axis-cgi/record/continuous/addconfiguration.cgi?diskid=SD_DISK
&options=resolution%3D640x480

http://<servername>/axis-cgi/record/continuous/addconfiguration.cgi?diskid=SD_DISK
&options=resolution=640x480

User access rights for CGI requests are determined by group membership.

In tables defining CGI arguments and supported values, the default value for optional arguments is system configured.

If an unknown argument is requested, for example if an argument is misspelled it will be ignored by the built-in server in the Axis product. That means that no response feedback will be given.

In many VAPIX API:s, responses are formatted according to an XML schema. Clients should always retrieve supported schema versions from the Axis product before sending other requests. In subsequent requests, the schema version must be specified. Make sure that the client and the Axis product use the same schema version.

http://<servername>/axis-cgi/disks/networkshare/schemaversions.cgi

http://<servername>/axis-cgi/disks/networkshare/list.cgi?schemaversion=1&shareid=all

Axis’ XML Schemas are available at http://www.axis.com/vapix/http_cgi/

XML schema versions

SchemaVersion=1.0

Content to be replaced

CGI requests

http://<servername>/axis-cgi/<subdir>[/<subdir>...]<cgi>.<ext>[?<argument>=<value>[&<argument>=<value>...]]

CGI response

<JPEG image data>

CGI example

http://myserver/axis-cgi/jpg/image.cgi

In some VAPIX API:s, for example the Call service API, requests can be constructed using JSON or using a simplified key-value format.

The simplified key-value format is a flattened structure with key=value strings. Levels in the structure are indicated by underscores (_).

• Boolean values are encoded as true and false.

• The NULL value is encoded as null.

• Strings are URL-encoded and may start and end with quotation marks. Example: "a+string%0A".

• Array keys are encoded as _index_ where index is an integer starting from 0.

Character sets are not converted or validated. UTF-8 is recommended.

-d'{"axcall:GetSIPConfiguration":{}}'

-d"{\"axcall:GetSIPConfiguration\":{}}"

$ curl --anyauth "http://root:pass@192.168.0.90/vapix/call" -s -d'{"axcall:GetSIPConfiguration":{}}'
{
  "SIPConfiguration": {
    "SIPEnabled": false,
    "TURNServers": [],
    "STUNServers": [],
    "ICEEnabled": false,
    "AllowIncomingCalls": false,
    "TURNEnabled": false,
    "STUNEnabled": false,
    "ApplyUserAuthentication": false,
    "AllowedUsers": [],
    "SIPPort": 5060,
    "SIPTLSPort": 5061,
    "ApplyAllowedURIs": false,
    "AllowedURIs": []
  }
}

$ curl --anyauth "http://root:pass@192.168.0.90/vapix/call?format=simple&action=axcall:GetSIPConfiguration"'
 
SIPConfiguration_SIPEnabled=false
SIPConfiguration_SIPPort=5060
SIPConfiguration_SIPTLSPort=5061
SIPConfiguration_STUNEnabled=false
SIPConfiguration_TURNEnabled=false
SIPConfiguration_ICEEnabled=false
SIPConfiguration_AllowIncomingCalls=false
SIPConfiguration_ApplyUserAuthentication=false
SIPConfiguration_ApplyAllowedURIs=false

$ curl --anyauth "http://root:pass@192.168.0.90/vapix/call?format=simple&action=axcall:GetSIPAccounts"'
 
SIPAccount_0_Id="sip_account_0"
SIPAccount_0_Username="local_account_ipv4_udp"
SIPAccount_0_Password=null
SIPAccount_0_Registrar=null
SIPAccount_0_PublicDomain=null
SIPAccount_0_IsDefault=false
SIPAccount_0_Transport="udp"
SIPAccount_0_CallerId="local_account_ipv4_udp"
SIPAccount_1_Id="sip_account_1"
SIPAccount_1_Username="1234"
SIPAccount_1_Password="password"
SIPAccount_1_Registrar="192.168.0.91"
SIPAccount_1_PublicDomain="exampledomain.com"
SIPAccount_1_IsDefault=true
SIPAccount_1_Transport="udp"
SIPAccount_1_CallerId="Entrance Door"
SIPAccount_1_DTMFConfigurationId="internal_config"
SIPAccount_2_Id="sip_account_2"
SIPAccount_2_Username="987654"
SIPAccount_2_Password="password2"
SIPAccount_2_Registrar=null
SIPAccount_2_PublicDomain="examplesecurity.se"
SIPAccount_2_IsDefault=false
SIPAccount_2_Transport="udp"
SIPAccount_2_CallerId="Entrance Door (Axis)"
SIPAccount_2_DTMFConfigurationId="remote_config"
SIPAccount_3_Id="sip_account_3"
SIPAccount_3_Username="12309"
SIPAccount_3_Password="password3"
SIPAccount_3_Registrar=null
SIPAccount_3_PublicDomain="[fd12:3456:789a:1::90]"
SIPAccount_3_PrioritizeIPv6=true
SIPAccount_3_IsDefault=false
SIPAccount_3_Transport="udp"
SIPAccount_3_CallerId="Entrance Door (Axis)"
SIPAccount_3_DTMFConfigurationId="remote_config"
SIPAccount_4_Id="sip_account_4"
SIPAccount_4_Username="local_account_ipv6_tcp"
SIPAccount_4_Password=null
SIPAccount_4_Registrar=null
SIPAccount_4_PublicDomain=null
SIPAccount_4_PrioritizeIPv6=true
SIPAccount_4_IsDefault=false
SIPAccount_4_Transport="tcp"
SIPAccount_4_CallerId="local_account_ipv6_tcp"

$ curl --anyauth "http://root:pass@192.168.0.90/vapix/call" -s -d'{"axcall:GetSIPAccounts":{}}'
{
  "SIPAccount": [
    {
      "Username": "local_account_ipv4_udp",
      "PublicDomain": null,
      "CallerId": "local_account_ipv4_udp",
      "Registrar": null,
      "Transport": "udp",
      "Password": null,
      "Id": "sip_account_0",
      "IsDefault": false
    },
    {
      "Username": "1234",
      "PublicDomain": "exampledomain.com",
      "CallerId": "Entrance Door",
      "DTMFConfigurationId": "internal_config",
      "Registrar": "192.168.0.91",
      "Transport": "udp",
      "Password": "password",
      "Id": "sip_account_1",
      "IsDefault": true
    },
    {
      "Username": "987654",
      "PublicDomain": "examplesecurity.se",
      "CallerId": "Entrance Door (Axis)",
      "DTMFConfigurationId": "remote_config",
      "Registrar": null,
      "Transport": "udp",
      "Password": "password2",
      "Id": "sip_account_2",
      "IsDefault": false
    },
    {
      "Username": "12309",
      "Registrar": null,
      "PublicDomain": "[fd12:3456:789a:1::90]",
      "SecondaryRegistrar": "",
      "SecondaryPublicDomain": "",
      "CallerId": "Entrance Door (Axis)",
      "DTMFConfigurationId": "internal_config",
      "Transport": "udp",
      "Password": "password3",
      "Id": "sip_account_3",
      "IsDefault": false
    },
    {
      "Username": "local_account_ipv6_tcp",
      "PublicDomain": null,
      "CallerId": "local_account_ipv6_tcp",
      "Registrar": null,
      "Transport": "tcp",
      "PrioritizeIPv6": true,
      "Password": null,
      "Id": "sip_account_4",
      "IsDefault": false
    }
  ]
}

$ curl --anyauth "http://root:pass@192.168.0.90/vapix/axast" -s -d'{"axast:PerformSpeakerTest":{}}'

{
  "Fault": "env:Receiver",
  "FaultCode": "ter:Action",
  "FaultSubCode": "axast:DeviceNotCalibrated",
  "FaultReason": "The Auto Speaker Test cannot be done without prior calibration.",
  "FaultMsg": null
}

$ curl --anyauth "http://root:pass@192.168.0.90/vapix/axast?format=simple&action=axast:PerformSpeakerTest"

Fault="env:Receiver"
FaultCode="ter:Action"
FaultSubCode="axast:DeviceNotCalibrated"
FaultReason="The Auto Speaker Test cannot be done without prior calibration."
FaultMsg=null

An API includes version numbering that consists of two numbers separated by a dot X.X. The first number represents the major version number of the API while the second represents the minor.

The following example is from an entry in the API Discovery service, where the version number of the API :

{
  "id": "basic-device-info",
  "version": "1.2",
  "docLink": "link to doc",
  "name": "API name as described in the VAPIX documentation."
}

Axis Communications uses both numbers to group new and/or upgraded functions. The numbers will increase for either the major or minor version depending on the change.

The major numbers of an API is changed when the API introduces an update that is backwards incompatible, i.e. when an existing client code ceases to work with the new API unless there are modifications done to it. Example of backwards incompatible changes are function signature changes, removal of a function or making an asynchronous function synchronous. To counter this, the API generally provides multiple sets of itself with different major numbers to make backwards compatibility possible when introducing new features.

The minor version of an API is changed to enhance functionality or fix bugs, which means that the client code should continue to work when there is a minor number change in the API.

As an example, a client implements a code to work with API version 1.0. The next release will then become API version 1.1. This means that the client code should work without any modifications.

A list of available APIs, together with their versions, can be retrieved through the API Discovery service, which makes it possible to retrieve information about APIs supported on a specific Axis product.

To be able to drive and control a VAPIX® device, a user must first be aware of the features that the device is supporting. A feature discovery can be made by using one of 3 different methods:

• API Discovery

• Feature API version

• Feature API informing capabilities

The order ranges from generic to a more specific feature discovery.

API Discovery

Feature API version

Feature API informing capabilities

Legacy feature discovery

The following examples will show you how to test your Ping or IP/port-address using the pingtest.cgi and tcptest.cgi.

Ping

To determine if your device is up and running and ready to ping another device or server on the network by searching for either its IP-address or the DNS-hostname, you should use the following URL:

http://<ip-address>/axis-cgi/pingtest.cgi?ip=ip-address

Port

To determine if your device is up and running and ready to reach another IP-address and port, i.e. test if the application itself is up and running on the server, you should use the following URL:

http://<ip-address>/axis-cgi/tcptest.cgi?address=ip-address&port=port