Cisco Evolved Programmable Network Manager 3.1 User and Administrator Guide
Bias-Free Language
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
Cisco Evolved Programmable Network Manager RESTful API
Cisco EPN Manager SDK
The Cisco EPN Manager SDK is a collection of technologies that enables you to extend the capabilities of Cisco EPN Manager, access data, and invoke the automation operations from any application. The Cisco EPN Manager SDK includes the RESTful APIs and Open Automation. It is possible to use the RESTful API with scripting languages such as
"bash with wget and cURL utilities", "Python", "Ruby", Java and so on.
With Cisco EPN Manager SDK technologies, you can:
Access Cisco EPN Manager programmatically—Use the Cisco EPN Manager RESTful API to invoke workflows and obtain reports.
Customize Cisco EPN Manager —Create custom workflow tasks, Customize Cisco EPN Manager by deploying your own jar files and script libraries in script modules. Use custom tasks from script bundles.
Cisco EPN Manager APIs
Cisco EPN Manager provides easy to use and comprehensive APIs that allow integration with any standards-based OSS system north bound. These
APIs extend its core functionalities using three of the most commonly used standards - MTOSI and RESTConf, and RESTful APIs.
To provide rapid development design for automation, it is important for developers to develop APIs consistently thus paving
way for a smoothest and easy to use design guidelines. Consistency allows teams to leverage common code, patterns, documentation
and design decisions. In Cisco EPN Manager, RESTful APIs are easily made available within the application with simple and extensive examples. The following diagram
is an example that illustrates the general behavior found in Cisco EPN Manager across *all* its APIs.
Figure 1. EPNM RESTful API General Behavior
This chapter is intended for the following technical professionals interested in using the Cisco EPN Manager Development Kit (SDK) and related technologies. Such users might be:
System administrators and REST API developers who use Cisco EPN Manager and want to extend their ability to automation resources using it.
Anyone else who wants to compare Cisco EPN Manager SDK or API technologies and determine which would be most appropriate for their application
Cisco EPN Manager provides three northbound API interface types, MTOSI, REST and RESTConf. The functionality provided by these three APIs are
fairly similar but not all APIs provide the same functions.
The MTOSI API is the most different of the APIs in terms of behaviour. It provides a SOAP interface over HTTPS that provides
basic provisioning of optical and carrier ethernet functionality. Use the MTOSI interface if you need to provision optical
services such as DWDM or OTN, and cannot use the RESTConf API.
The REST API provides system information and most statistics and assurance information besides other functions that handle
configuration files, group management and device import capabilities.
The RESTConf API, like the above REST API, adheres to a RESTful interface. It provides all provisioning for carrier ethernet,
L2/L3 VPNs, circuit emulation, OTN and DWDM technologies as well as core routing and switching.
Cisco EPN Manager RESTful API is a language-independent interface that can be used by any program or script capable of making HTTP requests.
Use the REST API when you want to invoke operations on Cisco EPN Manager from a separate program or process.
Applications can use the RESTful API to do the following:
Retrieve Cisco EPN Manager reports on physical and virtual devices, networks, appliances, groups and users, policies, and other monitored entities within
your Cisco EPN Manager domains.
Invoke additional operations specific to Cisco EPN Manager.
How to Use Cisco EPN Manager RESTful API
Because a RESTful API client interacts with Cisco EPN Manager using standard HTTP requests and responses, the RESTful API responses are compatible with any web browser. Many programming
languages have libraries devoted to creating and sending HTTP requests and handling HTTP responses.
Most of the REST API calls send and return data in the request or the response, respectively. These data payloads may be formatted
in one of two ways depending on the RESTful API call. Some of the RESTful API calls use a JavaScript Object Notation (JSON)
payload, while others use an XML payload. You probably have to use both for any reasonably complex application.
A JSON-based RESTful API call is a plain HTTP request and response with a JSON payload. JSON is a lightweight text-based open
standard designed for human-readable data interchange. JSON represents simple data structures and associative arrays. Your
application directly invokes the JSON-based API without using any specialized RESTful API libraries, and parses JSON data
using any means native to your application.
All requests to the Cisco EPN Manager API require user authentication. For more information about Authentication see Authentication and Authorization.
Authorization in the RESTful API is enforced by requiring that only registered users of Cisco EPN Manager are able to make API requests. For Cisco EPN Manager, access to the API is controlled by three user groups such as NBI Read, NBI Write and NBI Credentials (Deprecated). Each
of these groups controls access to a different set of APIs. You can assign a user to multiple groups if you wish. You can
check the documentation page of an API resource to determine which user group is required to access it. When a user is created
and registered on Cisco EPN Manager, the user is assigned a unique RESTful API access key.
To obtain the RESTConf topological link retrieval resources, you can use RESTful topological link resources to get these values
and perform the required correlation.
To access Cisco EPN Manager RESTful API documentation:
Launch Cisco EPN Manager, and then in the top right corner, click , the window settings menu opens.
Choose Help > API Help > REST API to learn about system requirements, how to set up a development environment, how to install libraries, usage of RESTful APIs,
the list of every Cisco EPN Manager REST API function, REST API Resources, different use case examples, queries and so on.
RESTConf API-An Overview
In Cisco EPN Manager, the implementation conforms to the RESTConf/Yang specification information model and operational APIs
protocols. Where required, the information model and operations APIs are extended in a standard way to support Cisco’s vendor
extensions to the RESTConf/Yang interface. These extensions are added as a set of xml and yang schema definitions for the
information model extensions.
RESTCONF—Uses structured data (XML or JSON) and YANG to provide a REST-like APIs, enabling you to programmatically access
different network devices. RESTCONF APIs use HTTPs methods.
YANG—A data modelling language that is used to model configuration and operational features . YANG determines the scope and
the kind of functions that can be performed by NETCONF and RESTCONF APIs.
Following are the essential structure of RESTConf API:
HTTP Headers: HTTP headers are used to describe the content sent or requested within an HTTP request. HTTP headers inlcude:
Content-Type: At server side, an incoming request may have an entity attached to it. To determine its type, server uses the
HTTP request header Content-Type.
Accept: Similarly, to determine what type of representation is desired at client side, HTTP header ACCEPT is used. Generally,
if no Accept header is present in the request, the server can send pre-configured default representation type.
HTTP Methods: The following methods are used to call an API:
Get-The GET method is sent by the client to retrieve data and metadata for a resource.
Post-It is used to create a new entity, but it can also be used to update an entity. The POST method is sent by the client
to create a data resource or invoke an operation resource.
Put-A PUT request is idempotent. The PUT method is sent by the client to create or replace the target data resource.
Delete-Request that a resource be removed. The DELETE method is used to delete the target resource.
Messages: The RESTCONF protocol uses HTTP messages. A single HTTP message corresponds to a single protocol method.
Media Types: XML and JSON.
Query Parameters:
Content
Depth
Fields
Filter
Insert
Point
Start-time
Stop-time
With-defaults
Standard usage - Get Method
The “GET All RESTConf API calls” returns the existing endpoint schema sections.
GET /restconf/data/ietf-yang-library:modules-state
Retrieves all RESTConf API endpoints
The schema URLs provide the details for many of the enumeration variables as well as the structural components of the module.
Example for schema retrieval:
GET /restconf/schema/v1/cisco-resource-optical
Returns the YANG schema for the module as plain text.
Several URL parameters are often available in RESTConf API calls. These are not implemented in all calls.
.maxCount
.startIndex
.depth
GET /restconf/data/v1/module:resource
The general format for a RESTConf GET call.
Table 1. Query Parameters
Query Parameter
Description
.depth (integer)
The number of detail levels to retrieve.
.maxCount (integer)
The limit of the number of rows retrieved.
.startIndex (integer)
The initial row to retrieve.
GET /restconf/data/v1/module:resource HTTP/1.1
RESTful API Utility
Fully Distinguishable Name: Inventory objects in this interface has attributes representing FDN (Fully Distinguished Name).
These attributes are used as identifiers of the object or as a reference to the object in query parameters or in the returns
data wherever a reference to the object is needed. This FDN is a formatted string that consists of a set of type/value pairs
with the following syntax, Sequence of <type>=<value> pairs separated by “!” where:
<type> is a constant value defined in the data model to represent the inventory object in the hierarchy, e.g. MD,ND,EQ,PTP,FTP,
CTP, TL,VC,CFS, etc.
<value> is any text or sequence of <attrName>=<attrValue> pair separated by “;” that represents the attribute/value pairs
of the inventory object constitutes a unique value within the local scope of the object represented by the type.
Alarms—The alarms module provides mechanisms to retrieve and acknowledge alarms and events. The preferred method of managing
alarms is to listen via the Notification API where a service can collect events of differing types or criticality and then
handle them via this API.
Performance Test—The Service Performance Test can be conducted standalone as well as part of service provisioning. Restconf
NBI supports standalone performance test execution.
Quality of Service (QoS)— QoS is a set of capabilities that allow the delivery of differentiated services for network traffic.
Using Cisco EPN Manager you can configure QoS on Carrier Ethernet interfaces.
OAM—The OAM tests in the EPNM RESTConf API fall into two general categories. The service and the network resource OAM configurations.
For Y.1731, Y.1564 and BERT tests, the service-oam-config endpoint is used. For OTDR, the network-resource-oam-config endpoint
is used. EPNM RESTConf OAM calls provide a POST command to initiate the test. That request yields a test ID and a test request
ID. One usually then uses the test ID in a subsequent call to retrieve the results. There are URLs for most specific test
types.
Service Profiles—Service Profiles contain pre-defined provisioning request (order data) that can be used in provisioning each
circuit/VC type. In NBI Provisioning request, a service profile reference can be used to get provisioning request data to
be used in the provisioning. If the provisioning data is provided in the request along with the service profile reference,
but the user provided data and the data stored in the service profile gets merged with user provided data overriding the profile
data before the request is sent to execute provisioning. Service profile can be created using EPNM Service Profile wizard
GUI.
Customer Facing Services (CFS)—The CFS represents the customer facing data for a circuit/VC. The CFS is derived from discovered
RFS and represents the endpoints of the circuit/VC in the network. During CFS discovery, the system creates CFS objects for
the discovered RFS objects.
Resource Facing Services (RFS)—The RFS represents the relations between resources on different devices. During RFS discovery,
the system creates device-level objects and network-level objects. Device-level RFS objects represent the circuit/VC configuration
parts of the device-level configuration. Network-level RFS objects aggregate device or other network-level objects to represent
network-level entities.
RESTConf API Functional Areas
Alarms—The alarms module provides mechanisms to retrieve and acknowledge alarms and events. The preferred method of managing
alarms is to listen via the Notification API where a service can collect events of differing types or criticality and then
handle them via this API.
Performance Test—The Service Performance Test can be conducted standalone as well as part of service provisioning. Restconf
NBI supports standalone performance test execution.
Quality of Service (QoS)— QoS is a set of capabilities that allow the delivery of differentiated services for network traffic.
Using Cisco EPN Manager you can configure QoS on Carrier Ethernet interfaces.
OAM—The OAM tests in the EPNM RESTConf API fall into two general categories. The service and the network resource OAM configurations.
For Y.1731, Y.1564 and BERT tests, the service-oam-config endpoint is used. For OTDR, the network-resource-oam-config endpoint
is used. EPNM RESTConf OAM calls provide a POST command to initiate the test. That request yields a test ID and a test request
ID. One usually then uses the test ID in a subsequent call to retrieve the results. There are URLs for most specific test
types.
Service Profiles—Service Profiles contain pre-defined provisioning request (order data) that can be used in provisioning each
circuit/VC type. In NBI Provisioning request, a service profile reference can be used to get provisioning request data to
be used in the provisioning. If the provisioning data is provided in the request along with the service profile reference,
but the user provided data and the data stored in the service profile gets merged with user provided data overriding the profile
data before the request is sent to execute provisioning. Service profile can be created using EPNM Service Profile wizard
GUI.
Customer Facing Services (CFS)—The CFS represents the customer facing data for a circuit/VC. The CFS is derived from discovered
RFS and represents the endpoints of the circuit/VC in the network. During CFS discovery, the system creates CFS objects for
the discovered RFS objects.
Resource Facing Services (RFS)—The RFS represents the relations between resources on different devices. During RFS discovery,
the system creates device-level objects and network-level objects. Device-level RFS objects represent the circuit/VC configuration
parts of the device-level configuration. Network-level RFS objects aggregate device or other network-level objects to represent
network-level entities.
Authentication and Authorization
All requests to the Cisco EPN Manager API require user authentication. If no authentication details are provided in the request, the request is redirected to the
login page. Authentication details may be passed through the HTTP header of the request. For more information see Authentication,
Authorization, and Security topic (Home > Authentication, Authorization, and Security ) in the Cisco EPN Manager API documentation.
For Cisco EPN Manager, access to the API is controlled by the user groups such as NBI Read, NBI Write, and NBI credential.
Each of these groups controls access to a different set of APIs. You can assign a user to multiple groups if you wish. You
can check the documentation page of an API resource to determine which user group is required to access it.
Note
It is recommended to use JSESSIONID during the production environment.
Getting Started with Cisco EPN Manager REST API
The Cisco EPN Manager REST API allows an application to interact with Cisco EPN Manager, programmatically. These requests provide access to resources in Cisco EPN Manager. With an API call, you can execute Cisco EPN Manager workflows and Monitor Alarms and Events, Collect device inventory, monitor network clients and usage, configure devices,
Device Inventory and so on. For more information see, the Getting Started topic (Home > Getting Started) in the Cisco Evolved Programmable Network Manager API documentation.
REST API Basics and Functional Areas
Cisco EPN Manager’s REST implementation uses multiple calls and filters. For example, when retrieving statistics, the first call provides URLs
for the subsequent calls. Those then can be used for retrieving finer detail. In general, the URL parameters become more complicated
with each call as more detail is added.
REST API Basics
HTTPS Headers: The following HTTP Headers are used to control the way in which data is returned to a client.
Accept
Accept-Language
Content-Type
Accept-Encoding
Content-Encoding
Query Parameters:
The API supports query parameters for almost all requests. The following table describes the General REST Query Parameters:
Table 2. General REST Query Parameters
Query Parameter
Applicability
Meaning
.json
/api/*
When present indicates that the response should be returned in json format.
.xml
/api/*
When present indicates that the response should be returned in xml format. This is the default in the absence of the .json
parameter.
_docs
/api/*
Displays the documentation page.
.full
/api/v1/data/T
When ‘true’ indicates that whole objects be returned rather than just IDs of the entities.
.group
api/v1/data/T
Filters the response based on content of the group specified by the string value, and the result of any applied operator.
.transform
GET/POST
Supplies the logical-name of a transform to be applied immediately before rendering to XML or JSON.
.maxresults
GET Paged
The greatest number of results in terms of the heads of instance trees returned.
.firstResult
GET Paged
The first result in terms of the heads of instance trees.
.strict
/api/v1/data/T
When ‘true’, the property names used in queries are validated, and an error thrown if appropriate. (The default - ie when
strict=false - is to ignore invalid property names with a simple log message).
.case_sensitve
/api/v1/data/T
When ‘true’, the string values used in filter queries are case sensitive. (The default - ie when .case_sensitive=false - is
to treat comparisons as case insensitive).
.nocount
/api/v1/data/T
When ‘true’, the “count”, “first”, and “last” attributes are not included the response. Getting the values of these attributes
requires additional time, therefore setting this to ‘true’ will improve performance. Defaults to ‘false’.
_ctx.domain
GET
Sets the active domain to be that named in the query parameter value - this is, by default, “sticky” in the sense that once
set, the active-domain remains set. The “stickiness” is not RESTful, and so it can be switched off in configuration.
REST API Functional Areas
Statistics: The Statistics services provide summary, pre-defined statistical information about the system. Some of the resources
of statistics are listed below.
GET All Border Routers
GET All IMEs
GET All RCs
GET All TCAs
GET All WANInterfaces
Report Service: The Report service provides operations to discover and run reports. Reports need to be defined in the system
prior to access through the API. The following APIs are supported:
GET Get Available Report Templates
GET Get a Report
GET Run a Report
GET Run a ZIP Report
CLI Template Configuration: The CLI Template Configuration service allows a CLI configuration template to be applied to one
or more target devices. It also provides a way to upload, delete, and get the CLI templates in the system. The following APIs
are supported:
GET CLI Configuration Templates
DELETE Delete Configuration Template
DELETE Delete Configuration Template Folder
GET Download Configuration Template
GET List Configuration Template Folders
GET List Configuration Templates
GET List Device Types
POST Create Configuration Template Folder
POST Upload Configuration Template
PUT Deploy Configuration Template
PUT Deploy Configuration Template Through Job
PUT Modify Configuration Template Content
Statistics
From EPNM you can acquire statistics data in a simple step by step process. This is a fairly consistent general pattern of
usage across several REST statistics endpoints. In general, a high-level first call is made that returns a list of available
metrics. From that call, a second list of finer statistics for a given metric is returned from which the actual data series
is returned.
Following is an example for Statistics - endpoint call succession: ESR PM data for a given circuit:
GET /webacs/api/v1/op/statisticsService/circuits?circuitName=VSO5_TO_HUB2
GET /webacs/api/v1/op/statisticsService/circuits/metrics?circuitType=ODUUNI&circuitId=161374613
GET /webacs/api/v1/op/statisticsService/circuits/metrics/ESR_PM?maxResults=24&timeInterval=6&endpoint-
Name=ODU20/4/0/0/1&location=FEND&circuitType=ODUUNI&deviceId=124606492_10.201.1.174&circuitId=161374613
Note
The URLs for the last two calls were provided in the body of the previous call.
, the window settings menu opens.
Feedback