Cisco V2PC API Service Guide - Release 3This guide is written for the knowledgeable API pr ogrammer who understands the basic architecture of the V2PC product and has some practical

Cisco Cisco Virtualized Video Processing Controller Release 3.3 API Service Guide

May 17, 2017

Cisco Systems, Inc.www.cisco.com

Cisco has more than 200 offices worldwide. Addresses, phone numbers, and fax numbers are listed on the Cisco website at www.cisco.com/go/offices.

http://www.cisco.com

http://www.cisco.com/go/offices

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS” WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

© 2017 Cisco Systems, Inc. All rights reserved.

http://www.cisco.com/go/trademarks

C O N T E N T S

C O N T E N T S

Overview 1-1

About the V2P Platform 1-1

About V2PC 1-2

V2PC Components 1-2

V2PC Concepts 1-3

V2PC API Methodology 1-5

HTTPS Response Codes 1-6

Managed Object Structure 1-6

V2PC Media APIs 1-7

Media Resource Management APIs 1-7

Media Service Discovery APIs 1-8

Media Asset Management APIs 1-8

Using the API Service 2-1

Finding API Definitions 2-1

Consuming the API 2-1

Role-Based Access Control 2-2

Sample API Definitions 3-1

Region Management 3-1

Retrieve All Region Objects 3-1

Retrieve a Region Object 3-2

Create a Region Object 3-4

Update a Region Object 3-5

Delete a Region Object 3-6

User Management 3-8

Create a User 3-8

Retrieve a User 3-10

Delete a User 3-11

Update a User 3-13

Object Definitions 3-15

iiiCisco Virtualized Video Processing Controller Release 3.3 API Service Guide

Contents

ivCisco Virtualized Video Processing Controller Release 3.3 API Service Guide

Preface

This guide describes the Cisco Virtualized Video Processing Controller (V2PC) API service introduced with V2PC Release 3.3.

The API service provides a more convenient, self-documenting alternative to the use of the Service Manager (SM) API. V2PC continues to support the SM API for compatibility with other components of the Cisco Virtualized Video Processing (V2P) suite of applications.

• Audience

• Document Organization

• Document Conventions

• Related Publications

• Obtaining Documentation and Submitting a Service Request

AudienceThis guide is written for the knowledgeable API programmer who understands the basic architecture of the V2PC product and has some practical experience developing content networking solutions. It is not intended to provide general instruction in API programming or content network management.

Document OrganizationThis document contains the following chapters:

Chapters or Appendices Descriptions

Overview Introduces the V2P platform and V2PC, and provides the conceptual background for the API.

Using the API Service Describes the use of the V2PC API service, which acts as an interactive API gateway to the V2PC platform.

Sample API Definitions Provides sample API definitions that show how the API service can be applied in practice.

vCisco Virtualized Video Processing Controller Release 3.3 API Service Guide

PrefaceDocument Conventions

Document ConventionsThis document uses the following conventions:

Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the manual.

Tip Means the following information will help you solve a problem. The tips information might not be troubleshooting or even an action, but could be useful information, similar to a Timesaver.

Caution Means reader be careful. In this situation, you might perform an action that could result in equipment damage or loss of data.

Timesaver Means the described action saves time. You can save time by performing the action described in the paragraph.

Warning IMPORTANT SAFETY INSTRUCTIONS

This warning symbol means danger. You are in a situation that could cause bodily injury. Before you work on any equipment, be aware of the hazards involved with electrical circuitry and be familiar with standard practices for preventing accidents. Use the statement number provided at the end of

Convention Indication

bold font Commands and keywords and user-entered text appear in bold font.

italic font Document titles, new or emphasized terms, and arguments for which you supply values are in italic font.

[ ] Elements in square brackets are optional.

{x | y | z } Required alternative keywords are grouped in braces and separated by vertical bars.

[ x | y | z ] Optional alternative keywords are grouped in brackets and separated by vertical bars.

string A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.

courier font Terminal sessions and information the system displays appear in courier font.

< > Nonprinting characters such as passwords are in angle brackets.

[ ] Default responses to system prompts are in square brackets.

!, # An exclamation point (!) or a pound sign (#) at the beginning of a line of code indicates a comment line.

viCisco Virtualized Video Processing Controller Release 3.3 API Service Guide

PrefaceRelated Publications

each warning to locate its translation in the translated safety warnings that accompanied this device.

SAVE THESE INSTRUCTIONS

Warning Statements using this symbol are provided for additional information and to comply with regulatory and customer requirements.

Related PublicationsRefer to the following documents for additional information about COS V2PC:

• Cisco Virtualized Video Processing Controller Release 3.3 Deployment Guide

• Cisco Virtualized Video Processing Controller Release 3.3 User Guide

• Cisco Virtualized Video Processing Controller Release 3.3 API Guide

• Release Notes for V2PC 3.3

• Open Source Used in V2PC 3.3

Obtaining Documentation and Submitting a Service RequestFor information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gathering additional information, see What’s New in Cisco Product Documentation at: http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html.

Subscribe to What’s New in Cisco Product Documentation, which lists all new and revised Cisco technical documentation, as an RSS feed and deliver content directly to your desktop using a reader application. The RSS feeds are a free service.

viiCisco Virtualized Video Processing Controller Release 3.3 API Service Guide

http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html

PrefaceObtaining Documentation and Submitting a Service Request

viiiCisco Virtualized Video Processing Controller Release 3.3 API Service Guide

Cisco Virtualized Video P

C H A P T E R 1
Overview
About the V2P PlatformThe Cisco Virtualized Video Processing (V2P) platform provides cloud based media ingest, packaging, storage, and origination functions for multi-screen video delivery. The V2P platform is a collection of well-defined applications that work together to deliver services to address media content use cases such as Linear TV, VOD, and Cloud DVR. As a whole, V2P takes input from media encoding systems and provides output to be consumed by and distributed to various client devices by a content distribution network (CDN).

Figure 1-1 Cisco Virtualized Video Processing (V2P) Platform

The V2P system can be instantiated in data center environments. Each V2P application is implemented as a modern distributed application with horizontal scaling and automated provisioning capabilities.

Based on the service definition, the composition of the applications within the service can be altered to allow operators the flexibility to choose the required capabilities.

1-1rocessing Controller Release 3.3 API Service Guide

Chapter 1 Overview About V2PC

About V2PCCisco Virtualized Video Processing Controller (V2PC) serves as the controlling application for the V2P platform. V2PC Release 3.3 supports Live, VOD, and cloud DVR media workflows.

V2PC ComponentsV2PC consists of four basic components:

• V2PC Platform and Service Management

• V2PC Service Manager (SM)

• Media Capture Engine (MCE)

• Media Playback Engine (MPE)

V2PC Platform Service and Management

V2PC Platform Service and Management resides in the primary V2PC node. This component abstracts the data center virtualization platforms for the application and creates the launch pad to launch the full V2PC system. It provides a container to host many of the common system level components such as databases, group coordination software, message queues, orchestration tools, and DNS proxy services.

V2PC Platform Service and Management hosts the main management and control functions of V2PC, including:

• Service Manager

• Resource Manager

• Application Instance Controllers

• Media Workflow Controllers

• Platform Instance Controllers

These functions are implemented as a collection of virtual machines, based on the high availability (HA) requirements defined for the system.

Note An odd number of virtual machines is required for fault tolerance.

V2PC Service Manager

Service Manager (SM) provides the API and GUI needed to administer the V2PC system and services. SM is hosted by primary V2PC node, and executes in the same virtual machine as Platform and Service Manager.

Media Capture Engine

Media Capture Engine (MCE) acquires media from various sources and packages the media in a common format and stores the package in the configured storage backend.

The format package includes the original media, metadata, and indexing. The media file format should be of the Adaptive Transport stream type. The system does not alter the source media files.

1-2Cisco Virtualized Video Processing Controller Release 3.3 API Service Guide


MCE is implemented as a set of virtual machines, also called Capture Workers. MCE capture sessions are controlled by MCE application controllers hosted by the primary V2PC node.

Media Playback Engine

Media Playback Engine (MPE) provides just-in-time packaging capabilities to repackage the common format content into various target formats for consumption across various end client devices. MPE also applies the required content protection to the target format contents, and integrates with various DRM ecosystems.

MPE is implemented as a set of virtual machines, also called playback workers. MPE playback sessions are controlled by MPE application controllers hosted by the primary V2PC node.

V2PC ConceptsWhen working with V2PC APIs, it is helpful to understand the following terms and concepts as they relate specifically to V2PC.

Media Workflow Domain

The Media Workflow Domain provides a logical container for hosting media and object storage services. The service operator is in charge of administering this domain. Media Workflow Domain objects make use of the V2P platform and infrastructure to configure the media workflows required for performing the supported services.

Media Workflows

A media workflow is a collection of resources, policies, and templates used to implement media ingest, control, storage, and playback for multi-screen use cases such as Live TV, VOD, and cDVR. A media workflow can orchestrate resources across regions.

Media Workflow Controller

A media workflow controller (MFC) is an instance of a V2PC media workflow. Multiple MFC instances can coexist. Each workflow instance is independently managed, monitored, and scaled.

Media Workflow Template

A media workflow template is a set of definitions for creating a specific V2PC media service. The template specifies the boundaries of the features and capabilities of the media workflow. Media workflow templates are not field-customizable.

Media Workflow Instance

A media workflow instance is created by instantiating a MFC instance that can support one or more media workflow templates.



Region

A region is an abstraction of the underlying cloud platform. A region may be associated with one or more data centers, a service area, or a geographic region. A region contains one or more zones.

Zone

A zone is a set of cloud components (for example, compute, network, storage, and security) that are logically fate-shared, such that they survive or fail as a unit. Zones can be mapped to the underlying cloud platform provider, such as a data center in vCenter or any other combination of cloud resource topologies to be treated as fate-shared. Each zone is associated with one cloud infrastructure provider.

Cloud Infrastructure Provider

A cloud infrastructure provider (for example, vCenter) is an abstraction representing cloud platform components such as compute hosts, networking components, storage, and security. A Resource Manager entity manages the cloud infrastructure provider configuration and its resources by using APIs specific to the technology it supports.

Resource Manager

A resource manager is a V2P application that maintains the resources represented by a particular cloud infrastructure provider configuration. Examples of such tasks include VM life cycle management and disk and network management.

Application Controller

An application controller is a set of code objects that provides the well-defined function or capability of a microservice. For example, an MCE application controller manages a cluster of MCE workers that provides media capture as a microservice.

Application Instance Controller

An application instance controller (AIC) is a runtime unit of an application. An AIC consists of a set of processes instantiated in one or more VMs that are used to manage the application instance and provide interfaces for working together with, configuring, or monitoring other application instances.

The AIC also manages the life cycle of its workers by instantiating as many VMs as are allowed and required by the policies for an application instance. An AIC is region-specific.

Application Worker

An application worker is a runtime machine instantiation (VM or appliance) that performs one or more of the tasks needed to fulfill the function or functions delivered by the application instance.

Application workers can be clustered for scaleout. Examples include media capture, media playback, and media storage.


Chapter 1 Overview V2PC API Methodology

Media Workflow

A media workflow instance is a specific binding of the end-to-end application processes, sockets, ports, and network interfaces needed to produce recordings or other media assets.

For example:

• A recording in progress service workflow might bind a media capture worker process or ports, a storage worker interface, and some workflow manager endpoints.

• A live playback service workflow using memory storage might bind a media capture worker process or ports, a media playback worker process or port, and optionally, a software load balancer path.

The basic function of a media workflow is defined by a media workflow template. Media workflow instances can be monitored and measured.

Media Workflow Template

A media workflow template defines the characteristic of a media workflow, including references to capture application instance, playback application instance, media ingest and publish formats, DRM profiles, asset life cycle policies, and asset redundancy policies.

Media Resource

A media resource is any resource used by a V2PC media workflow instance. Possible examples include a media source definition, a channel lineup, a DRM profile, external storage, or an external service.

Policy

A policy is a rule or constraint used by an application instance to control the delivery of a service level agreement (SLA) for a service instance. Possible examples include:

• Content redundancy policies for Unique Copy and Common Copy

• Content protection policies to define which DRM scheme to apply

• High availability (HA) policies to establish geographic redundancy

Policies define how applications are instantiated, what resources they use, and how long an asset exists.

V2PC API MethodologyV2PC system APIs use representational state transfer (REST) to manipulate and operate the states of the system and the services. A set of configuration objects is defined for each API classification. The configuration objects have a well-defined structure based on JavaScript Object Notation (JSON).

Configuration objects can be further classified in to reusable objects such as policies, resources, and templates, and objects specific to a service instance such as capture endpoints and playback endpoints.

Common objects such as policies, resources, and templates can be created once and then dereferenced across various other containers. Creating such reusable objects helps reduce the administrative overhead in repeating the configuration.

Note As a matter of good practice, create reusable objects before referencing in other configuration objects.


Chapter 1 Overview V2PC API Methodology

The API provides options to create, retrieve, update and delete (CRUD) using standard HTTPS methods.

• POST – Create Object

• GET – Retrieve Object

• PUT – Update Object

• PATCH – Update Managed Object

• DELETE – Delete Object

The PUT and PATCH methods are similar in effect, but differ in that PATCH allows the user to provide only attributes that require changing, while PUT requires the user to provide all attributes of the object.

All PUT (or PATCH) and POST methods with a body in the Request must set the ‘Content-Type’ header to ‘application/json’ unless noted specifically in the object APIs in this document.

HTTPS Response CodesV2PC Service Manager typically returns the following status in response to the REST HTTPS requests:

• 200 OK. This indicates that the REST request was successfully handled. For DELETE methods, multiple DELETE operation of the same REST resource also returns 200 OK.

A response body of the Content Type ‘application/json’ may be present depending on the operation. For certain resources like Service Instances, a PUT results in 200 OK, but there may be further operational errors that are subsequently reported as Events and Logs.

401 Not Authenticated. This indicates a failure to authenticate the requester based on the access token submitted with the request.

403 Not Authorized. This indicates that the requester was authenticated but does not have access to the requested service based on requester role assignments.

• 404 Not Found. This is a failure to find the REST resource for GET and PUT objects. No response body is returned.

• 400 Bad Request. This response indicates that the request was syntactically incorrect. The response body of Content Type ‘application/json’ is returned with ‘error’ description. This could be because of invalid URL structure composition, incorrect JSON structure in request body.

• 500 Internal Server Error. This indicates that the request could not be processed due to a failure in V2PC.

Managed Object StructureThe objects used by V2PC APIs are managed objects, and are identifiable and addressable directly.

Each object follows the same structure, as follows:

• Name – The name of an object is a unique label to identify that object within the scope of the object type and scope, such as a media workflow and application. For example, a ChannelSource can have the name ABC and a media workflow instance can also be named ABC, but two ChannelSources cannot coexist with the name ABC.

Id – A unique ID allocated by V2PC management to the management object. The Id is assigned by V2PC, and is returned in a GET response.


Chapter 1 Overview V2PC Media APIs

The Id is a read-only attribute and must be treated as an opaque reference. The Id is used as an object reference to form a connection between two objects. For example, the assetLifecyclePolicyRef in a LiveMediaWorkflow links the LiveMediaWorkflow object to an AssetLifeCyclePolicy object via the Id of AssetLifeCyclePolicy.

Note When objects are referenced by other objects, they cannot be deleted until the references are removed first.

• externalId – The URL for the object. The externalId is returned in a GET response.

• Type – The type or class of objects to which the object belongs. The Type is returned in a GET response.

• Properties – The Properties contain type specific key-values for an object.

V2PC Media APIsV2PC offers several APIs to control media workflow configuration, asset ingest process, and output format processing. The following API classifications are available.

Media Resource Management APIsMedia resource management APIs manage the lifecycles of media resource objects. Media resource objects are sets of sharable, reusable objects that represent basic media resource configurations such as a media source definition.

Media resource management APIs are applied within the media workflow domain to create workflow instances based on media workflow templates. The media workflow instance construct is used to bind applications and their configuration to implement well defined service workflows such as Linear, VOD, and Cloud DVR, based upon the constraints imposed by the templates.

Media resource management APIs make use of the following reusable objects:

• KeyProfile

• HTTPSHeaderPolicy

• ABRAssetPublishTemplate

• ESAMProfile

• NASStore

• AssetLifeCyclePolicy

• AssetRedundancyPolicy

• ChannelSource

• NASMediaSource

• DynamicSource

• ChannelLineup

• DynamicLineup

• StreamProfile


Chapter 1 Overview V2PC Media APIs

• AuthProfile

• COSStore

• NasStore

• ServiceAPI

Media Service Discovery APIsMedia service discovery APIs are provided to locate the asset manager that manages the recording assets for a media workflow after the workflow is enabled. Media service discovery APIs are region-specific.

Media Asset Management APIsMedia asset management APIs are provided to manage and control the media recording flow and discover the assets available in V2PC. Examples include:

• The recording management interface for a cDVR service instance

• VOD asset discovery for ingested assets for a VOD service instance

The Media Asset APIs are discoverable via the Media Service Discovery Interface.

The Media Asset Management APIs are invoked at a media workflow instance level to orchestrate ingest and packaging of media for the use cases defined by the media workflow template.

Media asset management APIs make use of the MediaAsset API reusable object.



C H A P T E R 2
Using the API Service
The V2PC API service is an interactive API gateway to the V2PC platform. Users interact with the API service through the OpenAPI Specification web user interface, also known as the Swagger UI.

The API service provides a common portal for both newer UI-specific API calls and legacy API calls to V2PC Service Manager (SM). The API service is accessed through port 8443, the port previously used for the SM API. The API service routes SM API calls to their new port assignment of 8444. In this way, the existence of two separate sets of API calls is made transparent to the user.

The API service is available on all V2PC master nodes. The service runs in active-active mode, meaning that the API client can consume (use) the API by connecting to any V2PC master node regardless of the active-standby state of the V2PC microservice.

Note To obtain Swagger UI and its user documentation, visit http://swagger.io/swagger-ui/.

Finding API DefinitionsTo access the V2PC API definitions from a locally installed version of Swagger UI, open Swagger UI in a web browser and point to:

<v2pc-master>:8043/docs

where <v2pc-master> is the IP address of any V2PC master node.

Note You can also view the V2PC API definitions through the online Swagger Editor by downloading the v2pcapi.yaml file from the Cisco software download page and uploading it to http://editor.swagger.io. The PDF version of the API can be extracted from v2pcapi.zip.

Consuming the APIAccess to the V2PC API is controlled by an access token. Before making API request, each API client must log in to the API service and request and receive an API token, as shown in the following examples:

Example Requestcurl -k -X POST --header 'Content-Type: application/json' --header 'Accept: application/json'


http://swagger.io/swagger-ui/

http://editor.swagger.io

Chapter 2 Using the API Service Role-Based Access Control

-d '{ "username": "sampleadmin", "password": "password" }' 'https://10.20.117.183:8043/api/ platform/login'

Example Response{"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwicm9sZXMiOlsiQWRtaW5pc3RyYXRvciJdLCJ0ZW ya-3xLow3nLrydnLNYsSH1vafJo19sOG8pDvBNtvQ-oKonmzqrjn78p5XB-To93S1OmzRf31KmLDXJ_o_VcwBvE9PhDXXefaWH5ZyuyrZDVVCxxmFvV8ZbHCsUuugmx5DoRbkAPeOeP8HNRbZHYWREUnA8KXX4 QEla_1ZtRlRN2AzxztzYkBO2mPjuvAK9CbvztMr28zFN9SYkZwLISQP1oydTQ0ozVPWduBTsa_m4eziNF3k6A8Yc1aINeMl1tQ"}

The API token is then used in the authorization header of each subsequent API request, as shown in the following example:

Sample Request with Tokencurl -X GET -k --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwicm9sZXMiOlsiQWRtaW5pc3RyYXRvciJdLCJ0ZW5hbnQiOiJk ya-3xLow3nLrydnLNYsSH1vafJo19sOG8pDvBNtvQ-oKonmzqrjn78p5XB- To93S1OmzRf31KmLDXJ_o_VcwBvE9PhDXXefaWH5ZyuyrZDVVCxxmFvV8ZbHCsUuugmx5DoRbkAPeOeP8HNRbZHYWREUnA8KXX4QEla_1ZtRlRN2AzxztzYkBO2mPjuvAK9CbvztMr28zFN9SYkZwLISQP1oydTQ0ozVPWduBTsa_m4eziNF3k6A8Yc1aINeMl1tQ" https://10.20.117.183:8043/api/platform/do/v2/regions/region-0/nodes

Role-Based Access ControlV2PC Release 3.3 supports role-based access control (RBAC). RBAC is a security enforcement method that assigns access permissions to user roles reflecting job functions, rather than to users directly. In the current release, V2PC has the predefined user roles:

• User

• Operator

• Administrator

Each V2PC user is assigned to one or more of these roles which, in turn, determine their access to APIs.

Each API has a corresponding minimum required role. For each API request, the API service checks the highest role associated with the request against the minimum required role for the API. This constitutes a first level of authorization; additional checks can be performed at the microservice level.

Because access is based on roles, there is no need for user-specific information in the API request, apart from the token in the API request authorization header.



C H A P T E R 3
Sample API Definitions
This chapter provides sample API definitions that show how the API service can be applied in practice. There are three categories of examples:

• Region Management, page 3-1

• User Management, page 3-8

• Object Definitions, page 3-15

Region ManagementThe Region Management API example includes the following API calls:

• Retrieve All Region Objects, page 3-1

• Retrieve a Region Object, page 3-2

• Create a Region Object, page 3-4

• Update a Region Object, page 3-5

• Delete a Region Object, page 3-6

Retrieve All Region Objects/api/platform/do/v2/regions

get:

tags: ["Service Manager - Platform"] <<< Define the API grouping category

description:

"Retrieve all Region objects."

operationId: "doRegionsGet" <<< Define the API routing implementation method name

produces: [application/json]

responses:

200:


Chapter 3 Sample API Definitions Region Management

description:

"Return an array of Region objects"

schema:

type:

"array"

items:

$ref:

"#/definitions/RegionWrap"

401:

description:

"Not authenticated"

403:

description:

"Not authorized"

500:

description:

"Service error"

security:

- UserRole: [] <<< Define the API minimum role

x-swagger-router-controller: "sm_route" <<< Define API routing implementation file name

Retrieve a Region Object/api/platform/do/v2/regions/{id}:

get:

tags: ["Service Manager - Platform"]

description:

"Retrieve a Region object."

operationId:

"doRegionGet"




parameters:

- name:

"id"

in:

"path"

type:

"string"

required: true

responses:

200:

description:

"Return a Region object"

schema:

$ref:


400:

description:

"User input error"

401:

description:

"Not authenticated"

403:

description:

"Not authorized"

404:

description:

"Region object not found"

500:

description:

"Service error"



security:

- UserRole: []

Create a Region Objectpost:


description:

"Create a Region object."

operationId:

"doRegionPost"

consumes: [application/json]


parameters:

- name:

"data"

in:

"body"

schema:

type:

"object"

$ref:


required: true

responses:

200:

description:

"Successfully created Region object, Return newly created Region object"

400:

description:

"User input error"

401:



description:

"Not authenticated"

403:

description:

"Not authorized"

500:

description:

"Service error"

security:

- UserRole: []

Update a Region Objectput:


description:

"Update a Region object."

operationId:

"doRegionPut"



parameters:

- name:

"id"

in:

"path"

type:

"string"

required: true

- name:

"data"

in:

"body"



schema:

$ref:


required: true

responses:

200:

description:

"Successfully updated a Region object"

400:

description:

"User input error"

401:

description:

"Not authenticated"

403:

description:

"Not authorized"

404:

description:


500:

description:

"Service error"

security:

- UserRole: []

Delete a Region Objectdelete:


description:



"Delete a Region object."

operationId:

"doRegionDelete"


parameters:

- name:

"id"

in:

"path"

type:

"string"

required: true

responses:

200:

description:

"Successfully deleted a Region object"

400:

description:

"User input error"

401:

description:

"Not authenticated"

403:

description:

"Not authorized"

404:

description:


500:

description:

"Service error"


Chapter 3 Sample API Definitions User Management

security:

- UserRole: []

x-swagger-router-controller:

"sm_route"

User ManagementThe User Management API example includes the following API calls:

• Create a User, page 3-8

• Retrieve a User, page 3-10

• Delete a User, page 3-11

• Update a User, page 3-13

Create a User/api/platform/mgmt/v1/user:

post:

tags: ["User Management"]

description:

"Create a user in the tenant. require tenant admin privilege to access."

operationId:

"userPost"



parameters:

- name:

"user"

in:

"body"

description:

"User object to be created"

required: true

schema:

$ref:

"#/definitions/User"



- name:

"api_key"

in:

"query"

description:

"Optional api key as query parameter instead of as http header"

required: false

type:

"string"

responses:

200:

description:

"New user created"

schema:

$ref:


400:

description:

"User input error"

401:

description:

"Not authenticated"

403:

description:

"Not authorized"

500:

description:

"Service error"

security:

- AdminRole: [] <<< Define the API minimum role




"platform_route"

Retrieve a User/api/platform/mgmt/v1/user/{username}:

get:


description:

"Retrieve a specific user. Require user privilege to access."

operationId:

"userGet"


parameters:

- name:

"username"

in:

"path"

description:

"User with id equals to username to be retrieved"

required: true

type:

"string"

- name:

"api_key"

in:

"query"

description:


required: false

type:

"string"

responses:

200:

description:

"Return a user object"



schema:

$ref:


401:

description:

"Not authenticated"

403:

description:

"Not authorized"

404:

description:

"User does not exist"

500:

description:

"Service error"

security:

- UserRole: []

Delete a Userdelete:


description:

"Delete a specific user. Require admin privilege to access."

operationId:

"userDelete"

parameters:

- name:

"username"

in:

"path"



description:

"To be deleted user's username"

required: true

type:

"string"

- name:

"hardDeletion"

in:

"query"

description:

"Boolean flag whether delete the user permanently"

required: false

type:

"boolean"

- name:

"api_key"

in:

"query"

description:


required: false

type:

"string"

responses:

200:

description:

"Successfully deleted a user"

401:

description:

"Not authenticated"

403:

description:

"Not authorized"

404:



description:


500:

description:

"Service error"

security:

- AdminRole: []

Update a Userput:


description:

"Update a specific user. Require admin privilege to access."

operationId:

"userPut"



parameters:

- name:

"username"

in:

"path"

description:

"To be updated user's username"

required: true

type:

"string"

- name:

"updatedUser"

in:

"body"

description:

"Updated user object."

required: true



schema:

$ref:


- name:

"api_key"

in:

"query"

description:


required: false

type:

"string"

responses:

200:

description:

"Successfully updated a user"

schema:

$ref:


401:

description:

"Not authenticated"

403:

description:

"Not authorized"

404:

description:


500:

description:

"Service error"


Chapter 3 Sample API Definitions Object Definitions

security:

- UserRole: []


"platform_route"

Object Definitionsdefinitions:

User:

type:

"object"

required:

-

"username"

-

"password"

properties:

username:

type:

"string"

firstname:

type:

"string"

lastname:

type:

"string"

email:

type:

"string"

phone:

type:



"string"

password:

type:

"string"

format:

"password"

roles:

type:

"array"

items:

$ref: "#/definitions/Role" <<< Refer to another object definition

tenant:

type:

"string"

notes:

type:

"string"

pwdrecovery:

type:

"array"

items:

$ref:

"#/definitions/PwdRecoverQuestion"

example:

username:

"admin"

firstname:

"John"

lastname:

"Doe"

email:



phone:

"800-555-1212"

password:

"secret"

roles: [{"rolename": "Administrator", "tenant": "smtenant_0"}]

tenant:

"smtenant_0"

pwdrecovery: [{question: "What was your first car?", answer: "Ferrali Spider"}]

notes:

"This is an example user"

Role:

type:

"object"

required:

-

"rolename"

properties:

rolename:

type:

"string"

enum:

- User

- Operator

- Administrator

tenant:

type:

"string"

example:

rolename:

"Administrator"

tenant:

“smtenant_0”




Documents

Cisco V2PC API Service Guide - Release 3This guide is written for the knowledgeable API pr ogrammer who understands the basic architecture of the V2PC product and has some practical