Request/Response structure

Request Structure

Kaltura API requests are standard HTTP POST/GET, URL encoded requests targeted to a specific API method. Each API method location is concatenated out of base URI, service and action identifiers strings, according to the following format:

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

where[SERVICENAME] represents the specific service and [ACTIONNAME] represent an action to be applied on the specific service.

For example, a request to activate the “list” action of the “media” service should be posted 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:

• Input parameters should be sent as a standard URL encoded key-value string.
• When input parameter is an object, it must be flattened to pairs of ObjectName:Param keys.
• When date value is being passed as input parameter it should follow the YYYY-MM-DD HH:MM:SS format.

Example:

id=abc12&name=name%20with%20spaces&entry:tag=mytag&entry:description=mydesc&cdate=2001-02-04%2003:11:32

Within this example the following parameters are being URL encoded and passed as API input parameters:

id = “abc”
name = “name with spaces”
entry {
	tag = “mytag”,
	description = “mydesc”	
}
cdate = “2001-02-04 03:11:32”

Response Structure

Kaltura API response content is gziped by default (assuming client specifies it supports gzip). Every response content is wrapped in an XML formatted container object, holding a <result> element.

Successful Response

When Kaltura server executes an API request successfully, the <result> element within response’s body will hold a structure of parameters relevant for the specific request. Response’s <result> structure could be simple, holding one or few parameters, or complex, holding many parameters including nested objects.

Example of Successful Response:

<?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 Kaltura server fails to execute a specific API request, an <error> element will be nested within response’s <result> element. The <error> element will hold information on response error code and the equivalent error message.

The following table lists few possible general API error codes and their equivalent messages:

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 exists
ACTION_NOT_SPECIFIED	Action name was not specified, please specify one
ACTION_DOES_NOT_EXISTS	Action "%ACTION_NAME%" does not exists 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

Example of an error Response

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