Using Http; Http Xmlapi Authentication; Http Xmlapi Session Authentication - Cisco TelePresence SX10 Reference Manual

Cisco TelePresence SX10

Introduction

Using HTTP

The codec supports sending commands and configurations
over HTTP and HTTPS. It is also possible to retrieve configu-
rations 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 combina-
tion 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
Authentication. The response sets a SessionId-cookie that
can be used with subsequent requests.
Note that when using API Session Authentication, it is impor-
tant 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.
Cisco TelePresence SX10 API Reference Guide CE8.2, SEPTEMBER 2016.
D15333.07
About the API About the API xConfiguration
URL cheat sheet
The following table contains the main URLs used when accessing the API over HTTP.
Method
GET
GET
GET
GET
GET
POST
Example: Starting a HTTP XMLAPI session
Request:
POST /xmlapi/session/begin HTTP/1.1
Authorization: Basic <Base64 encoded authentica-
tion 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
with Basic Access
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
xCommand
URL
http://<ip-address>/status.xml
http://<ip-address>/configuration.xml
http://<ip-address>/command.xml
http://<ip-address>/valuespace.xml
http://<ip-address>/getxml?location=<path>
http://<ip-address>/putxml
38
API Reference Guide
xStatus
Description
Complete status document
Complete configuration document
Complete command document
Complete valuespace document
Retrieve document based on a path
Configurations and commands in HTTP body
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
Copyright © 2016 Cisco Systems, Inc. All rights reserved.
Appendices