1 Introduction to Cisco VDS Service Broker APIs (

1 Introduction to Cisco VDS Service Broker APIs  (
CH A P T E R
1
Introduction to Cisco VDS Service Broker APIs
Cisco Videoscape Distribution Suite Service Broker (VDS-SB) software provides HyperText Transport
Protocol Secure (HTTPS) web services APIs that comply with the REpresentational State Transfer
(REST) standard, Java API for XML RESTful Web Services (JAX-RS), version JSR-311.
This chapter contains the following sections:
•
RESTful APIs, page 1-1
•
Calling the HTTPS APIs, page 1-2
•
API Status Codes, page 1-3
RESTful APIs
In RESTful web services APIs, the URL is used to uniquely identify a resource that can be mapped to
one domain object or a collection of domain objects. Each URL (called a resource URL) exposes uniform
interfaces to the API clients. The API clients call the URLs by way of the standard HTTP methods of
POST, GET, PUT, and DELETE. The HTTP methods are used to describe the create, read, update, and
delete (CRUD) actions to be performed.
VDSM exposes RESTful web service APIs through HTTPS by way of port 8443. Extensible Markup
Language (XML) is used as the data format for the request body and response body.
The VDSM provides the following RESTful HTTPS APIs:
•
CDN Management
•
BFQDN Management
•
BFQDN Policy
•
CDN Adaptation Policy
•
CDN Selection Policy
•
Service Broker
•
File Management
All URLs starting with “/api/” are RESTful APIs that are intercepted by the VDSM REST service.
Cisco VDS Service Broker 1.2 API Guide
OL-30254-01
1-1
Chapter 1
Introduction to Cisco VDS Service Broker APIs
Calling the HTTPS APIs
Authentication and Authorization
VDSM uses a basic authentication method to authenticate the API user. As an example, the following
GET request returns all existing CDN in the response body:
https://admin:default@<vdsm_ip>:8443/api/CDN
For more information, see the Cisco VDS SB 1.2 Software Configuration Guide or the VDSM online
help.
ID Format
All ID variables ({id}, {id2}, and so on.) in the URL templates (URLs with variables are called URL
templates) should be substituted with the long integer value of the corresponding objects.For example,
the CDN URL is https://admin:default@<vdsm_ip>:8443/api/CDN/{id}; so for a VDSM with an IP
address of 192.168.1.25 and an CDN ID of 193, the URL is
https://admin:default@192.168.1.25:8443/api/BFQDNs/193.
Note
The admin password, default, is the built-in admin password, and is used as an example. We strongly
recommend that you change the built-in admin password as soon as possible. To do so, log in to the CLI
of the VDSM device, and use the username admin password <password> global configuration
command.
The “id,” and “uri” are identity attributes returned along with the XML response body to the API client.
As a general rule, the POST method is used to create an object that is allocated a new ID, and the PUT
method is used to modify an object that is identified by a resource URL. The ID is part of the URL if a
resource type has multiple objects; otherwise, the ID is not needed if the resource object represented by
the URL only has one instance.
Calling the HTTPS APIs
You can execute the VDSM APIs interactively or through a caller program. API calls must follow the
correct syntax. If the user credential is invalid or the syntax is incorrect, the API is not executed. If a user
error occurs, a specific standard HTTP error code is returned (for example, 400, 403, 404, 500, and so
on).
Note
All API parameters are case sensitive.
Two headers must be set for the HTTPS API requests:
•
Accept —Accept header must be specified to indicate what content type the API client expects to
receive from VDSM API services, supported values are: application/xml, or application/json
•
Content-Type—Content-Type header must be specified to indicate the content type of the request
body the API client sends to the VDSM API services, supported values are: application/xml, or
application/json
Cisco VDS Service Broker 1.2 API Guide
1-2
OL-30254-01
Chapter 1
Introduction to Cisco VDS Service Broker APIs
API Status Codes
Interactive Calls
Use a REST client plug-in for a browser or Lynx command to execute the API interactively. The browser
address bar only supports the GET method; however, the VDSM APIs use all HTTP methods. The user
is prompted to enter a username and password for authentication and authorization. Once the user is
validated, the API is executed. If the execution is successful and an output is to be returned as a result,
the output is displayed in the browser if a browser was used to make the API call, or the output can be
redirected to a file if a Lynx command was used to make the API call. If the execution is unsuccessful,
an error message is returned.
Programmed Calls
To make an API call, write a caller program using an HTTPS request. The username and password are
set in the HTTPS request for AAA validation. If validation and execution are successful and an output
is to be returned as a result, the output or a success code is returned. If the execution is unsuccessful, a
failure code is returned.
API Status Codes
The VDSM return HTTP response codes.
Error Status Codes
If a server error occurs while the APIs are invoked, the error message is reflected in an HTTP response
code; for example, 404 not found. All error codes are standard HTTP response codes. If an error occurs,
an XML-formatted or json- formatted message is returned.
The following HTTP error status codes may be returned:
•
400 Bad Request. (When the request body is not valid XML message required by specific APIs)
•
403 Authorization failure
•
404 Not found: the requested URL or the requested resource object doesn't exist.
•
500 Internal Error
Following is an example of error case:
curl -u admin:default -k -i -H "Content-Type: application/xml" -X GET
"https://10.74.23.40:8443/api/LiveChannels/111"
HTTP/1.1 404 Not Found
Date: Wed, 24 Oct 2012 08:13:20 GMT
Server: Apache
Content-Length: 175
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorResponse uri="/api/LiveChannels/111">
<error>The requested object is not found: 111</error>
</ErrorResponse>
Following is an example of an XML-formatted message:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ErrorResponse uri="/api/LiveChannels/111">
Cisco VDS Service Broker 1.2 API Guide
OL-30254-01
1-3
Chapter 1
Introduction to Cisco VDS Service Broker APIs
API Status Codes
<error>The requested object is not found: 111</error>
</ErrorResponse>
Following is an example of a json-formatted message:
{
"@uri": "/api/LiveChannels/22",
"error": "The requested object is not found: 22"
}
Success Status Codes
Success status codes consist of 200 OK, 201 Created (with Location header: the URI of the new created
resource) and 204 No Content (OK with empty response body). The 204 codes may be returned for the
following:
•
POST—For create operation, the Location header of the response returns the URI of the new created
resource object. The response body is empty.
•
PUT—Used when modifying a resource object. The modify request is handled, 204 is returned with
empty response in the response body.
•
DELETE—Used when deleting a resource object. The delete request is handled, 204 is returned with
empty response in the response body.
Cisco VDS Service Broker 1.2 API Guide
1-4
OL-30254-01
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising