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 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.

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 behavior. 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.

For more information see the individual Cisco EPNM integration guides available on cisco.com.

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.

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 that are 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 that is 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 and NBI Write. 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.

• 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.

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 and NBI Write. 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	We recommended to use JSESSIONID during the production environment.

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.

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.