Vantage Cloud API Guide

Cloud API Guide

166556 July 15, 2015

Copyrights and Trademark Notices2

Vantage Cloud API Guide

Copyrights and Trademark NoticesCopyright 2015 by Telestream, LLC. All rights reserved worldwide. No part of this publication may be reproduced, transmitted, transcribed, altered, or translated into any languages without the written permission of Telestream. Information and specifications in this document are subject to change without notice and do not represent a commitment on the part of Telestream.

Telestream, CaptionMaker, Episode, Flip4Mac, FlipFactory, Flip Player, Lightspeed, ScreenFlow, Switch, Vantage, Wirecast, GraphicsFactory, MetaFlip, and Split-and-Stitch are registered trademarks and MacCaption, e-Captioning, Pipeline, Post Producer, Tempo, TrafficManager, and VOD Producer are trademarks of Telestream, LLC. All other trademarks are the property of their respective owners.

Telestream, LLC848 Gold Flat RoadNevada City, CA 95959 USA

You can call Telestream. via telephone at (530) 470-1300.

Part number: 166556

Date: July 15, 2015

3

Contents

Vantage Cloud API Guide 1Copyrights and Trademark Notices 2

Contents 3

Overview 5Introduction 5

Who Needs This Guide? 5What Can You Do with the Vantage Cloud API? 6What Languages Can You Use? 8Vantage Cloud API Overview 8

State Diagram and Description 11Stable States 12Transition States 12Actions 14Other API Calls 14

Use Cases 15Introduction 15Getting Started 16

Important Help Notes 16Deploying a Client Application 18

Creating, Starting, and Stopping a Virtual Domain 18

Glossary 21

Contents4

Vantage Cloud API Guide

5

Overview

IntroductionThis guide describes the Vantage Cloud API, an Application Programming Interface that allows you to write your own control program to manage the functions of Vantage Cloud Subscriptions. You can automate specific features or program your own Windows or Web client user interface using any programming language you prefer.

Reference documentation, code examples, and other resources are available on the Telestream Vantage Cloud Subscriptions Support web page:http://www.telestream.net/telestream-support/vantage-cloud/support.htm

The guide chapters cover these topics:

Overviewan introduction to the API Use Casesexamples Glossarya glossary of terms youll need to know

This chapter introduces and provides an overview of the Vantage Cloud API. These topics are included:

Who Needs This Guide? What Can You Do with the Vantage Cloud API? What Languages Can You Use? Vantage Cloud API Overview State Diagram and Description

Who Needs This Guide?This guide is written for programmers who are tasked with writing a custom interface to Vantage Cloud Subscriptions. You must be a programmer capable of writing client applications in a common programming language. Examples are presented in a later chapter to help you get started.

Note: Early versions of the API included a SOAP interface, which has been replaced by REST. The SOAP interface is still included in Vantage Cloud but is deprecated.

Vantage Cloud API Guide

http://www.telestream.net/telestream-support/vantage-cloud/support.htm

Overview6

What Can You Do with the Vantage Cloud API?The Vantage Cloud service exposes a REST API to allow interaction with Vantage Virtual Domains from a client that you develop.

REST clients can be implemented in a wide variety of languages, making it very easy to acquire and modify a client to send API commands to the Vantage Cloud API. The Postman REST API client for Google Chrome is recommended for testing and exploring the API.

For more information about REST and Postman, refer to the following resources:

General information: https://en.wikipedia.org/wiki/Representational_state_transfer

REST client by Google, Postman: https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcb-ncdddomop

The following information presents an overview of how to fully integrate the application you write with Vantage Cloud.

Overview of Vantage Cloud SubscriptionsThese are the components of Vantage Cloud Subscriptions:

1. Vantage Virtual Domainsinstances of Vantage Software running at AWS.2. Vantage SDKan SDK interface to the Vantage Domain for the automation of job

submission and task management of transcoding operations.

3. Vantage Cloud Servicethe windows service that communicates with AWS to provision, monitor, and manage Vantage Virtual Domains.

4. Vantage Cloud Managerthe application software that is the graphical user interface to the Vantage Cloud Service.

5. Vantage Cloud APIthe application programming interface to the Vantage Cloud Service to enable the programmed control of Vantage Virtual Domains.

Steps to Integrate with Vantage Cloud Using the APIThese are the general steps you will follow to integrate with Vantage Cloud:

1. Install Vantage Cloud on a local machine, called the Vantage Cloud Host. See the Vantage Cloud Manager Users Guide provided in the Help menu of Vantage Cloud Manager for installation details.

2. Download and install a REST test application, such as Postman, onto a User Application Host. Test clients are readily available from many different sites. The Application Host machine can be the same as the Vantage Cloud Host. Later you

Vantage Cloud API Guide

https://en.wikipedia.org/wiki/Representational_state_transferhttps://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop

Overview 7

will use this machine to host your client application, which acts as a client to the Vantage Cloud API running on the Vantage Cloud Host.

See the Use Cases chapter, and also see the Vantage Cloud API Reference document for API command definitions and code examples.

3. Provision a Virtual Domain using the Vantage Cloud API.

4. Optionally, extend your application on the User Application Host to act as a client to the Vantage SDK running on the Domain Instance in the Virtual Domain created in step 3. This will give you control of Vantage from your client application.

You will need this information for accessing the Vantage SDK:

a. The Domain Instance IP, available through the Vantage Cloud API.b. The Vantage SDK API documentation.

See the examples in the Use Cases chapter, and also see the Vantage Cloud API Reference document for API commands, syntax, and details.

Vantage Cloud API Guide

Overview8

What Languages Can You Use?You can use any programming language suited to the task of programming a client for Vantage Cloud Subscriptions using the Vantage Cloud API. However, using a current common language is recommended so you can get support from Telestream. If you choose an unusual language, the support available to you may be limited.

Vantage Cloud API OverviewThe Vantage Cloud REST API exposes the complete set of features available in Vantage Cloud. The API adheres generally to REST principles but does not claim to be RESTful in its strict definition. For example; the API does not in general support HATEOAS and uses some query parameters to add verbs not supported in the standard HTTP methods.

API VersionsAs new API versions are released, integrators can choose to target a specific past version or the latest one.

EndpointsThe API is available on any host where Vantage Cloud Manager is installed and running. These are the base endpoint URIs:

Latest version (currently version 1): http://[HOST]:43000/VantageCloudRest/ Version 1: http://[HOST]:43000/VantageCloudRest/v1/

HelpThe API exposes a dynamic help endpoint at this location:

http://[HOST]:43000/VantageCloudRest/Help

The help endpoint returns an HTML formatted document with information about all supported endpoints and HTTP methods together with a short description.

For more information about the request and response format, follow the HTTP method link in the help listing.

For more information about operations, see the referenced Vantage Cloud API Ref-erence operation (this is the API documentation for the SOAP interface). Here you will find more detailed descriptions of the operations together with data contract information (notice that the data contracts differ slightly between the REST and the SOAP interfaces.

Request and Response FormattingThe API expects and returns JSON formatted data. Make sure that the HTTP header Content-Type is set to application/json when sending requests to the API.

Vantage Cloud API Guide

http://[HOST]:43000/VantageCloudRest/http://[HOST]:43000/VantageCloudRest/v1/http://[HOST]:43000/VantageCloudRest/Help

Overview 9

ErrorsError messages of the following types may be returned.

Endpoint Errors

Incorrectly formatted endpoint URIs or unknown endpoint URIs return an HTTP status code 404 (Not Found) together with an HTML formatted document with a general "Service" message including a link to the API help endpoint.

Request Formatting Errors

Incorrectly formatted requests (usually incorrectly formatted JSON request data) returns an HTTP status code 400 (Bad Request) together with an HTML formatted document with a general "Request Error" message.

Vantage Cloud Operation Errors

Errors in specific Vantage Cloud operations return an HTTP status code and JSON formatted error information.

The API responds with one of the following HTTP status codes:

Client Error - 400 Bad Request: Indicating that there was a problem with the request data, for example a data validation error.

Client Error - 401 Unauthorized: Indicating that th