D15335.08 Cisco TelePresence MX700 and MX800 API Reference Guide CE9.2, NOVEMBER 2017.
Copyright © 2017 Cisco Systems, Inc. All rights reserved.
33
Cisco TelePresence MX700 and MX800
API Reference Guide
Using HTTP
The codec supports sending commands and configurations
over HTTP and HTTPS. It is also possible to retrieve
configurations and statuses this way. This interface exposes
the same API as the command line, but in XML format.
HTTP XMLAPI Authentication
Access to the XMLAPI requires the user to authenticate using
HTTP Basic Access Authentication as a user with ‘ADMIN’
role. Unauthenticated requests prompt a 401 HTTP response
containing a Basic Access Authentication challenge. How to
use HTTP Basic Access Authentication varies according to
the HTTP library or tool that you are using.
If your application will be issuing multiple commands
through the API, we highly recommend that you use Session
Authentication (see below). The standard basic authentication
does a full re-authentication per request, which may affect
the performance of your application.
HTTP XMLAPI Session Authentication
Authenticating with your username and password
combination for each API request might introduce too
much latency for some use-cases. To mitigate this, the API
supports a session-based authentication mechanism.
To open a session, issue a POST to
http://<ip-address>/
xmlapi/session/begin
with Basic Access Authentication. The
response sets a SessionId-cookie that can be used with
subsequent requests.
Note that when using API Session Authentication, it is
important to explicitly close the session when you are done.
Failing to do so may cause the device to run out of sessions,
as there are a limited number of concurrent sessions
available, and they do not time out automatically.
Example: Starting a HTTP XMLAPI session
Request
:
POST /xmlapi/session/begin HTTP/1.1
Authorization: Basic <Base64 encoded
authentication string>
Response
:
HTTP/1.1 204 No Content
Server: nginx/1.8.0
Connection: keep-alive
Set-Cookie: SessionId=f08102c8ce5aaf8fba23a7238
cc2ef464b990e18bfbb7fb048820c0e28955c54; Path=/;
HttpOnly
This session counts toward the systems concurrent sessions
limit.
With an open session, provide the SessionId cookie to
following requests. Your tool/library may do this automatically.
Example: Using a HTTP XMLAPI session
Request
:
GET /configuration.xml HTTP/1.1
Cookie: SessionId=f08102c8ce5aaf8fba23a7238cc2ef46
4b990e18bfbb7fb048820c0e28955c54
Response
:
HTTP/1.1 200 OK
Server: nginx/1.8.0
Content-Type: text/xml; charset=UTF-8
Content-Length: 43549
Connection: keep-alive
<?xml version=”1.0”?>
<Configuration product=”Cisco Codec”
version=”ce8.2.0” apiVersion=”4”> ...
</Configuration>
To close a session after use, issue a POST to http://<ip-
address>/xmlapi/session/end with the provided cookie.
Example: Closing a HTTP XMLAPI session
Request
:
POST /xmlapi/session/end HTTP/1.1
Cookie: SessionId=f08102c8ce5aaf8fba23a7238cc2ef46
4b990e18bfbb7fb048820c0e28955c54
Response
:
HTTP/1.1 204 No Content
Server: nginx/1.8.0
Connection: keep-alive
Set-Cookie: SessionId=; Max-Age=0; Path=/;
HttpOnly
URL cheat sheet
The following table contains the main URLs used when accessing the API over HTTP.
Method
URL
Description
GET
http://<ip-address>/status.xml
Complete status document
GET
http://<ip-address>/configuration.xml
Complete configuration document
GET
http://<ip-address>/command.xml
Complete command document
GET
http://<ip-address>/valuespace.xml
Complete valuespace document
GET
http://<ip-address>/getxml?location=<path>
Retrieve document based on a path
POST
http://<ip-address>/putxml
Configurations and commands in HTTP body
Introduction
About the API
xConfiguration
Appendices
xCommand
xStatus
About the API
