Kaltura API Usage Guidelines

Printer-friendly version

This document describes how to:

  • Access the Kaltura application programming interface (API)
  • Use the Kaltura API

To learn the basics about the Kaltura API and API architecture, refer to Introduction to the Kaltura API Architecture.

Applicability

This document applies to Kaltura API version 3 and later.

Document Conventions

A string in brackets [] represents a value.

Replace the string – including the brackets – with an actual value.

Example: Replace [SERVICENAME] with syndicationFeed.

Prerequisites

To access the Kaltura API, you require:

  1. A Kaltura publisher account - To obtain a Kaltura account, start a free trialcontact us or Download Kaltura CE.
  2. Obtain your Kaltura API publisher credentials via the KMC Integration Settings

Finding the Latest API Version Number

To find the version number of the API that contains the latest updates:

Go to the full XML description of the API schema: http://www.kaltura.com/api_v3/api_schema.php

The version and date of the API schema appear near the beginning of the file.

API Schema Version Data Example

<xml apiVersion="3.1.3" generatedDate="1312093534">
- <!--  Generated on date 31/07/11 02:25:34   -->

The generatedDate value is a UNIX timestamp.

Using the Kaltura API Test Console

The Kaltura API Test Console web page enables you to interact with the entire Kaltura API using a simple user interface (see the figure below).

You use the Test Console to:

  • Browse the Kaltura API.
  • Try out the Kaltura API without writing code.

To learn more and get started with the TestMe Console, refer to Kaltura API and TestMe Console Introduction.

Getting a Client Library for the Kaltura API

To work with the Kaltura API, you need code that can:

  • Construct a Kaltura request.
  • Perform an HTTP request.
  • Parse the result of a Kaltura request.

To save you time, Kaltura provides client libraries. A client library is a set of classes that includes:

  • The functional infrastructure for communication with the Kaltura API: constructing a request, performing an HTTP request, and parsing a response
  • A full object representation of all the entities that are available through the Kaltura API, including enumeration objects
  • Infrastructure for developers, such as built-in log capabilities

The Kaltura API SDK includes client library packages in different languages, including PHP, Java, C#, and JavaScript. For the latest version of all client libraries, refer to Kaltura API SDK - Native Client Libraries.

To get the entire API in your IDE, just download the client library for the language that you use to develop your applications and include the client library in your application or project.

To learn more about the client library structure and how to use a client library, refer to Kaltura API: Introduction to Kaltura Client Libraries: Technical Guide.

Getting a Client Library for a Language that Kaltura Does Not Provide

The Kaltura client libraries are generated automatically based on API schema (see Finding the Latest API Version Number).

As an open-source project, Kaltura strives to include contributions from the community and customers. Kaltura welcomes contributions of client libraries for languages that Kaltura does not yet provide.

You can write a custom generator class in PHP that generates code in the language of your choice.

If you provide the generator class to Kaltura, Kaltura will include your generator class in the Kaltura core generator. The new client library will be automatically generated and will be publicly available.

For more information on creating a client library generator, refer to Adding New Kaltura API Client Library Generator.

API Authentication and Kaltura Sessions

Most Kaltura API calls require you to authenticate before executing a call.

Calls that require authentication usually have a response that cannot be shared between different accounts. For the Kaltura server to know that you are allowed to “ask that question,” you must authenticate before executing the call.

To learn more about the Kaltura Session and API Authentication, read: Kaltura's API Authentication and Security.

Kaltura API Response/Request Format

Request Structure

The Kaltura API implements a standard HTTP POST/GET URL encoded request structure. URL-encoded requests are targeted to a specific API method.

Each API method location is concatenated from:

  • Base URI
  • Service identifier string
  • Action identifier string

The format of the API method location is:

http://www.kaltura.com/api_v3/?service=[SERVICENAME]&action=[ACTIONNAME]

where

  • [SERVICENAME] represents a specific service.
  • [ACTIONNAME] represent an action to be applied in the specific service.

Request URL Example

Post a request to activate the list action of the media service to the following URL:

http://www.kaltura.com/api_v3/?service=media&action=list

Request Input Parameters

Each API method receives a different set of input parameters.

For all request types:

  • Send input parameters as a standard URL-encoded key-value string.
  • When an input parameter is an object, flatten it to pairs of ObjectName:Param keys.

Request Input Parameters Example

id=abc12&name=name%20with%20spaces&entry:tag=mytag&entry:description=mydesc

In the example, the following parameters are URL encoded and are passed as API input parameters:

id = ‘abc’
name = ‘name with spaces’
entry {
	tag = ‘mytag’,
	description = ‘mydesc’	
}

Response Structure

When a client supports gzip, the content of a Kaltura API response is compressed with gzip by default.

Supported Kaltura API response formats include the following:

  • XML (Default)
  • JSON
  • PHP
  • JSONP

To work with a non-default format, append the format parameter to the query string of a request.

Response Structure Example

To receive a JSON output of a request, use following URL:

http://www.kaltura.com/api_v3/?service=media&action=list&format=1 

Numeric IDs of the most commonly used formats:

  • RESPONSE_TYPE_JSON = 1;
  • RESPONSE_TYPE_XML = 2;
  • RESPONSE_TYPE_PHP = 3;
  • RESPONSE_TYPE_JSONP = 9;

Successful Response: XML Format

When Kaltura server successfully executes an API request, the <result> element within the response body holds a structure of parameters that are relevant for the specific request.

A response <result> structure may be simple or complex:

  • A simple structure holds from one to a few parameters.
  • A complex structure holds many parameters, including nested objects.

Successful Response Example

<?xml version="1.0" encoding="utf-8" ?> 
<xml>
  <result>
    <objectType>KalturaMediaEntry</objectType>
	<id>vcnp8h76m8</id>
	<name>Demo Video</name>
	<description/>
	<partnerId>1</partnerId>
	<userId/>
	<tags/>
	<adminTags>demo</adminTags>
	<status>2</status>
	<type>1</type>
	<createdAt>1240844664</createdAt> 
  </result>
  <executionTime>0.08957796096802</executionTime> 
</xml>

Error Response

When the Kaltura server fails to execute a specific API request, an <error> element is nested in the response <result> element.

The <error> element holds the response error code and the error message.

The table lists some general API error codes and corresponding error messages.

Text enclosed in quotes and percentage signs ("%) is a placeholder for dynamically replaced values.

The actual message contains the specific value that the request passes.

For an exhaustive list of error codes, review the KalturaErrors class.

Error Code

Error Message

INTERNAL_SERVERL_ERROR

Internal server error occurred

MISSING_KS

Missing KS, session not established

INVALID_KS

Invalid KS "%KS%", Error "%KS_ERROR_CODE%,%KS_ERROR_DESCRIPTION%"

SERVICE_NOT_SPECIFIED

Service name was not specified, please specify one

SERVICE_DOES_NOT_EXISTS

Service "%SERVICE_NAME%" does not exist

ACTION_NOT_SPECIFIED

Action name was not specified, please specify one

ACTION_DOES_NOT_EXISTS

Action "%ACTION_NAME%" does not exist for service "%SERVICE_NAME%"

MISSING_MANDATORY_PARAMETER

Missing parameter "%PARAMETER_NAME%"

INVALID_OBJECT_TYPE

Invalid object type "%OBJECT_TYPE%"

INVALID_ENUM_VALUE

Invalid enumeration value "%GIVEN_VALUE%" for parameter "%PARAMETER_NAME%", expecting enumeration type "%ENUM_TYPE"

INVALID_PARTNER_ID

Invalid partner id "%PARTNER_ID%"

INVALID_SERVICE_CONFIGURATION

Invalid service configuration. Unknown service [%SERVICE_NAME%:%ACTION_NAME%].

PROPERTY_VALIDATION_CANNOT_BE_NULL

The property "%PROPERTY_NAME%" cannot be NULL

PROPERTY_VALIDATION_MIN_LENGTH

The property "%PROPERTY_NAME%" must have a min length of %MININUM_LENGTH% characters

PROPERTY_VALIDATION_MAX_LENGTH

The property "%PROPERTY_NAME%" cannot have more than %MAXIMUM_LENGTH% characters

PROPERTY_VALIDATION_NOT_UPDATABLE

The property "%PROPERTY_NAME%" cannot be updated

INVALID_USER_ID

Invalid user id

Error Response Example

<?xml version="1.0" encoding="utf-8" ?> 
<xml>
  <result>
    <error>
      <code>MISSING_KS</code>
      <message>Missing KS. Session not established</message>
    </error>
  </result>
  <executionTime>0.011207971573</executionTime>
</xml>

API Errors and Error Handling

The Kaltura API can return errors.

API errors are represented by an error identifier followed by a description:

  • An error ID is a unique string. The parts of the string are separated by underscores.
  • An error description is textual. The description may include a dynamic value.

A comma separates the error ID from the description.

API Error Example

ENTRY_ID_NOT_FOUND,Entry id "%s" not found 

%s is replaced with the value that is sent to the API call.

In the response XML:

  • The <code> node contains the error code (such as ENTRY_ID_NOT_FOUND).
  • The <message> node contains the description (such as Entry id “%s” not found).

See Error Response for a detailed code example.

Error Handling

In most client libraries, the client library code throws an exception when an error is returned from the API.

Depending on the programming language, catching the exception to read the code and/or the message enables user-friendly error handling.

Errors that you encounter during development usually are caused by incorrect implementation.

The Multirequest API

Understanding the Multi-Request Feature

The Kaltura API can execute several API calls in a single HTTP request to Kaltura.

The multi-request feature improves performance in Kaltura integrations.

The feature enables a developer to stack multiple API calls and issue them in a single request. This reduces the number of round-trips from server-side or client-side developer code to Kaltura.

The Kaltura API processes each of the API calls that are included in the single HTTP request. The response essentially is a list of the results for each of the calls in the request.

The multi-request feature includes the ability to have one request depend on the result of another request.

While the Kaltura API is processing each of the API calls in a multi-request, it detects when there is a dependency in one of the call parameters. The Kaltura API parses the dependency and replaces it with the result of the relevant call.

Using the Multi-Request Feature

Multi-Request with Dependency: Sample Use Case

To create a new entry out of a file in your server, you execute several different API calls:

  1. uploadToken.add
  2. uploadToken.upload
  3. baseEntry.addFromUploadedFile

The result of uploadToken.add is an uploadToken object that consists of a token string.

You need the token string when executing the next action – uploading the file. So you must complete the first action in order to call the second.

Using the multi-request feature, in the second request you specify obtaining the value of the token parameter from the token property that is the result of the first request.

Multi-Request Structure

To perform a multi-request call:

  1. Define the GET parameter of service as multirequest and define action as null:
    http://www.kaltura.com/api_v3/?service=multirequest&action=null
  2. Prefix each API call with a number that represents its order in the multi-request call, followed by a colon. Prefix the first call with 1:, the second with 2:, and so on.
  3. Use the prefix for each of an API call's parameters (service, action, and action parameters).

Multi-Request Structure Example

Request URL: api_v3/index.php?service=multirequest&action=null
	POST variables:
		1:service=baseEntry
		1:action=get
		1:version=-1
		1:entryId=0_zsadqv3e
		2:service=flavorasset
		2:action=getWebPlayableByEntryId
		2:entryId=0_zsadqv3e
		2:version=-1
		ks={ks}

Multi-Request with Dependency: Structure

To create a multi-request with a dependent request:

Use the following structure as input in the variable whose value you want to replace with a result of a preceding request:

{num:result:propertyName}

where:

  • num is the number of the request from which to collect data.
  • result instructs the Kaltura API to replace this value with a result from another request.
  • propertyName is the property to obtain from the object of the required result.

Multi-Request With Dependency: Example

	Request URL: api_v3/index.php?service=multirequest&action=null
	POST variables:
		1:service=media
		1:action=list
		1:filter:nameLike=myentry
		2:service=media
		2:action=get
		2:entryId={1:result:objects:0:id}
		ks={ks}

In the example, the first request lists entries whose names resemble myentry.

The media.list request returns an object of type KalturaMediaListResponse, which contains an object named objects of type KalturaMediaEntryArray.

The second request is media.get, which uses entryId as input.

The entryId input is dynamic, and the value is obtained from the first request. Since the media.list response is constructed of array object within a response object, the first property to access is KalturaMediaEntryArray.

Since in KalturaMediaEntryArray you want to obtain the first element (index 0), you add :0 to the request value.

Since from the first element you want only the ID that is the input for the second request, you add :id to the request value.

Document type: 
(54837 reads)