Hide Navigation
Navigation
  
Overview
Product Documentation
Data Model
API flows
Client Libraries
Services
General Objects
Error Codes

Kaltura OTT APIOverview

Edit on GitHub

Kaltura OTT > Phoenix principles - Overview

Overview

About this document

This page contains an overview of the Phoenix API's design principles. It is aimed both at those who are responsible for using the Phoenix APIs (architects, developers, testers, integrators) and those who are responsible for extending it (Kaltura R&D team members).

Governance

The Phoenix API and its design principles are owned and and governed by the Kaltura Systems Architecture team. This team is responsible for changes in the present document and approval of specific new and changed Phoenix APIs. The evolution of the Phoenix design principles and of the API itself is driven by the Kaltura Product organisation's requirements and is impacted by the software architecture and development needs and capabilities (the Software Architecture team and Development Team are consulted). There are exceptional cases when the Phoenix API doesn’t follow the principles described in the present document. Reasons for this can include:

  1. The API is legacy and there is no reason to deprecate it
  2. The API is an evolution of legacy, or must be aligned with legacy, and there is no reason for revolutionary changes
  3. There are software architecture and/or development aspects that require an exceptional definition of the API that is not aligned with the principles as they are defined here

    Phoenix APIs (including special cases where the conventions that are described in the document are not followed) must be approved by the Kaltura Systems Architecture team.

Glossary of terms

Before using the Phoenix APIs, the reader should be familiar with the following terms:

Term Meaning
Asset An entity that is managed by KTP and represent tangible or virtual asset. For example program details, VOD details, subscription metadata.
Channel (KalturaChannel) A set of Kaltura assets, selected manually or dynamically, using predefined filters (also is called Collection).
--- ---
CRUD Acronym of: Create, Read, Update and Delete
--- ---
EPG Electronic Program Guide: An application used with digital set-top boxes and newer television sets to list current and scheduled programs that are or will be available on each channel and a short summary or commentary for each program. EPG is the electronic equivalent of a printed television program guide.
Household (HH) Household is the billed entity (sometimes called account). Household is associated with payment method/s. An entity that can contain one or more User profiles that are managed by a its authorized user/s. A Household, which is also referred to as a Domain, is a container for Users, devices, entitlements, and limitations.
Group A Kaltura OTT account owned by an operator. Group and partner are synonyms, and are used in the interchangeably.
KS Kaltura Session: A valid KS must be passed with each call to Kaltura’s API. The session context embedded into a KS identifies the application, content access permissions, and API access permissions (it also contains other internal session data). This information is securely encrypted and hashed, preventing unauthorized manipulation of the session context.
Live Media Asset (EPG Channel) Equivalent to a TV channel, this represents a set of EPG programs related to the same playable source on a single timeline.
OTT Over The Top: Video transmitted via the Internet without an operator of multiple cable controlling or distributing the content.
OTT User A specific user account that must be associated with household account.
VOD Video On Demand: Allows end users to watch video content whenever the user chooses.
Phoenix Action A Phoenix API method. Phoenix methods (actions) are grouped in logical “services”. An action as a concept, is a CRUD operation, in the service context and, impacts only the service entity.
Notes:
1. Read action (e.g. get) might populate the response object with information that belongs to its associated services (e.g. asset.images)
2. An endpont of Phoenix action is of the form: /service/{{service name}}/action/{{action name}} (e.g. …/service/asset/action/add)
Phoenix Service A Phoenix service represents group of methods that related to the same Phoenix entity/object (e.g. household service represents set of actions that are releated to and might impact KalturaHousehold instance/s).
System event An internal, CRUD or logical, KTP event that cause KTP to fire message to a messages BUS.
KTP system events preferably are fired as Kafka log events that exposed to KTP only and relayed to external Kafka instance/s if it is required (e.g. to, partners extensions Kafka instance).
Legacy system events are fired in RabbitMQ messages BUS that is used by KTP and partner extensions

Phoenix API

Phoenix APIs are a set of provider APIs that are defined by the Kaltura TV Platform (KTP).

Phoenix APIs consist of service actions for querying, setting, updating and listing KTP entities, as well as for activating processes within KTP. Actions are grouped according to the entity type they are applied to. The grouping name (or in Phoenix terminology the service name) is derived from the name of the entity type in question. A Phoenix service provides all actions that are applied to the entity in question.

For example, categoryItem service groups together four actions:

add - add new KalturaCategoryItem to KTP (of partner in question).

delete - delete specific KalturaCategoryItem instance from KTP (of partner in question).

list - list the KalturaCategoryItem instances in KTP (of partner in question).

update - update specific KalturaCategoryItem instance in KTP (of partner in question).

Protocol Overview

Phoenix APIs are based on standard HTTP POST/GET url-encoded requests and described using the OpenAPI standard (see Phoenix service/action End to End Examples).

Phoenix API infrastructure is flexible and enables exposing the same API in several ways:

  1. API implementation can expose the same action as HTTP GET and/or HTTP POST interchangeably
  2. Each API get as argument “format” query parameter to enable requester to define the desired response format (e.g., JSON or XML)
  3. Request’s argument/s can be sent on different locations (i.e. path parameters, query parameters and body parameters).

IMPORTANT:

  1. Phoenix API requests are JSON based and XML format is considered deprecated and not supported
  2. Per API, the documentation shall define what is supported

2.1. HTTP method (POST or/and GET) 2.2. API arguments - per argument: name, type and its location (i.e. header, path, query, or body) 2.3. Per API, the documentation shall explicitly define the supported response formats (JSON, XML, JSONP, ASSET_XML, EXCEL)

API Fundamental Concepts

Phoenix APIs are conceptually divided to services.

A service represents a resource in the data model that groups all actions that relevant to it. For example, OTT-User, Recording, Asset.

A resource in the data model is an entity/class in Phoenix data model that has unique identifier, named ‘id’. Conceptually, resource id is unique in the group/partner context only, but in the existing implementation, resource id is unque globally (in the context of the environment)

An action represents an operation that is relevant to the resource in question. Specific action expects known arguments and returns known objects. The best practice is:

  1. to support just add, update, list and delete actions per service (named: core actions).
  2. delete action return true for sccess and error otherwise.
  3. other actions of a service, expected to return object/s that is/are type of the resource that the service in question

    Exceptions:

    1. Service includes only subset of the core actions. For example assetComment exposes only add and list actions. Rasons:
      • The action isn't required by any of the existing roles.
    2. Service includes more then the core actions. For example announcement exposes enableSystemAnnouncements and updateStatus actions in addition to the core actions. Reason:
      • Exposes easy to use, API to enable partial resource update.
    3. Action of serivce X return object/s that is/are not type of the service representative. For example service/ottUse/action/login return KalturaLoginResponse. Reason:
      • Actions of service that represents collection of calculated objects that are not maintained in the data model as entities, and its configuration get/update actions (e.g. ingestStatus actions)
      • Other architectural reason. E.g. instead of defining e.g. session.startWithAppToken it was decided to define appToken.startSession

Design, service or action that doesn’t satisfy the best practices is considered exception, and shall be confirmed with system architect.

A Phoenix API request URL form is: {{prefix}}/{{API Version}}/service/{{service name}}/action/{{action name}} (in short it will be named: {{service name}}.{{action name}})

Parameter Name Description Examples
{{prefix}} protocol + DNS name + path https://api.prod_env.ott.kaltura.com
{{API Version}} The API version api_v3
{{service name}} The service name. 1. asset 2. ottUser 3. household
{{action name}} The action 1. add 2. update 3. list

Resources naming convention

Phoenix resource MUST have a meaningful name that starts with "Kaltura" prefix and follows the CamelCase notation (e.g., KalturaHouseholdDevice - see here)

Service naming convention:

Service name is based on its associated Kaltura resource name. To transform Phoenix resource name to its Phoenix service name:

  1. Omit the "Kaltura" prefix (in our example KalturaHouseholdDevice ).

  2. Must follows the lowerCamelCase notation (see here) - Replace the first letter with its lowercase letter (in our example KalturaHhouseholdDevice )

Actions naming convention:

Action MUST have a meaningful name that describes the action/operation's objective (e.g. add, list, login, etc.) and follows the lowerCamelCase notation (e.g. loginWithPin - see here)

Common actions

The following table presents resource's common actions

Action Description Note
add Add a new resource.
- The added resource MUST be the one that the service in question represents.
- Request MUST includes object type of the resource in question.
- Request MUST include all the required fields that are not controlled by KTP.
- The added resource will be populated with the resource that is sent in the request.
- Response MUST be the added resource for success or standard Phoenix error
- Conceptually add action fires CRUD system event
* Because of performance considerations, not all add operations fire CRUD event		 Fields that are not controlled by KTP:
1. id
2. created date
3. updated date
* Any exception must be clearly defined in the API documentation
update Update an existing resource
- The updated resource MUST be the one that the service in question represents.
- Request MUST include object type of the resource in question.
- Request MUST NOT include fields that are controlled by KTP or marked as read only beside the resource id.
- Response MUST be the updated resource for success or standard Phoenix error
- Conceptually update action fires CRUD event
* Because of performance considerations, not all update operations fire CRUD event
- id of the updated resource MUST be provided.
- If the requested id doesn't exist the response will be error
delete Delete an existing resource
- The deleted resource MUST be the one that the service in question represents.
- Request MUST include id of the resource in question named: 'id'.
- The minimum set of identifiers to identify the deleted resource uniquely should be sent
- 'id' should be the identifier for the resource itself
- In cases that an extra identifier is required to uniquely identify the deleted resource, the delete argument name shall be:
- If the extra param has dedicated type then the extra identifier type name, in lowerCamelCase (type of the identifier)
- If it is id of other resource named X then the form of the name shall be {{X}}Id
- Response SHOULD include true for success or standard Phoenix error.
- Conceptually delete action fires CRUD event*
* Because of performance considerations not all delete operations fire CRUD event		 In many cases the body includes boolean value == true for success.
Example of delete action that requires extra identifier to uniquely identify the deleted resource:-
Resource name: KalturaAsset
- Unique identifier: <id, AssetReferenceType>
→ delete action request body includes two fields:
1. id - the asset id
2. assetReferenceType - the type of the asset (type of AssetReferenceType)
Documentation MUST clearly define if delete action does something different from only deleting the resource in question.
get Get a specific resource- The requested resource MUST be the one that the service in question represents.
- Request MUST include id of the resource in question named: 'id'.
- The minimum set of identifiers to identify the requested resource uniquely should be sent
- 'id' should be the identifier for the resource itself
- In cases that extra identifier is required to uniquely identify the requested resource, the requested argument name shall be:
- If the extra param has dedicated type then the extra identifier type name, in lowerCamelCase (type of the identifier)
- If it is id of other resource named X then the form of the name shall be {{X}}Id
- Response MUST be the requested resource for success or standard Phoenix error		 Get action can be implemented using the list action and sometimes it is omitted.
list Request to get list of resources (e.g. KalturaAsset) based requested filter.- Request potentially includes two fields:
- filter - defines the characteristics of the requested resource/s (type MUST inherit from: KalturaFilter)
- pager - in cases where the response includes many items there is an option to use KalturaFilterPager and specify the "page" to retrieve
- Response MUST be type of KalturaAssetListResponse for success or standard Phoenix error
- The type of item, in the "objects" array of the response, MUST be type of the service's resource in question
- The number of items in the list MUST not be more than the requested page size		 The filter always defines what resources should be included in the response.

Notes:

  1. KTP action request shall be inherited from OTTRequest.

  2. Request documentation MUST clearly define per action argument:

    • Valid values

    • Existence expectation and how it impacts the opration in question

      • required argument - must be marked with star ('*') and sent to the action in question

      • required argument inner field - must be marked with star ('*') and sent to the action in question

      • readOnly argument inner field - must not be sent to add and update actions

      • insertOnly argument inner field - must not be sent to update actions

      • Optional argument inner field that isn't sent to add action will be left empty

      • Optional argument inner field that isn't sent to update action

        2.1. If the argument is type of KalturaOTTObjectSupportNullable then the missing optional fields won't be updated.

        2.2. If the argument isn't type of KalturaOTTObjectSupportNullable then the missing optional fields will be updated and get an empty value.

        2.3. In exception cases that (1) or (2) isn't satisfied, it must be well documented.

  3. Response documentation MUST clearly define

    3.1. Success response

    3.2. Valid error values

    3.3. The supported response format

Phoenix Request Structure

Phoenix request includes common arguments that are included in the body root JSON object (OTTRequest).

Additional arguments shall always be wrapped with request object.

Legacy action request and its new extensions dedicated arguments might be included in the root of the body JSON object in parallel to the common arguments of the OTTRequest (and be added as new argument that wrap inner arguments in dedicated request object).

Common Arguments

KalturaRequestConfiguration

KalturaRequestConfiguration schema includes list of common request arguments.

By default the following input parameters are assumed to be available for all Phoenix APIs with the meanings described here UNLESS the API definition explicitly state otherwise.

Name Type Description
ks string Kaltura Session (KS)
partnerId integer The group id that call is relevant to
userId integer The user id that the call is done on behalf of (if it is not provided then it is taken from the KS)
apiVersion string The API versionExample: "7.2.0"
language string The language code that shall be used when interpreting the call request in questionExample: "en"
clientTag string A string that tag the client.Based on the clientTag the KTP classfies clients,The clientTag is used:1. To mark the logs 2. To decide whether asset's meta and tags response will include system names or its alias. Exmaple: "TVMng"
currency string The currency code that shall be used when interpreting the call request in questionExample: "US"
responseProfile KalturaBaseResponseProfile A mechanism to enrich the response
*Multireuqset *arguments
abortAllOnError boolean Abort all following requests in Multireuqset if current request has an error
abortOnError boolean Abort the Multireuqset call if any error occurs in one of the requests
skipCondition KalturaSkipCondition Skip action based on one of t he inherited skip condition classes

KalturaFilter

Phoenix list action expected two arguments "filter" and "pager".

"filter" argument must be an object tha is inherited from KalturaFilter object that is an abstract class.

Instance of KalturaFilter defines a selection criteria for the list action in question, and defines what are the resources that belongs to the list action's response, and its order (named: responseResourceList).

The response itself includes all or part of the responseResourceList resources depends on the requested page size and index (see KalturaPager section)

Filter characteristics

  • "filter" argument specify what resources shall be part of the response

  • "filter attribute" defines condition that specify what resource shall be included in the response and its order

  • Only resources that satisfy all the "filter attribute" conditions shall be included in the response (unless it is explicitly defined differently)

  • All filters shall be inherted from KalturaFilter.

  • Filter attributes are of the form: {resource attribute name}LogicalOperation

    • New filters MUST use existing LogicalOperation terminology (if applicable)

Filter attribute naming convention:

:

"Filter attribute" name Description Note
{resource attribute name}GreaterThanOrEqual The value of {resource attribute name} in question greater than or equal to the specified value Resource field name expected to be type of number
{resource attribute name}LessThanOrNull The value of {resource attribute name} in question is null or it is less than the specified value Resource field name expected to be type of number
{resource attribute name}LessThanOrEqualOrNull The value of {resource attribute name} in question is null or it is less than or equal to the specified value Resource field name expected to be type of number
{resource attribute name}GreaterThanOrNull The value of {resource attribute name} in question is null or it is greater than the specified value Resource field name expected to be type of number
{resource attribute name}GreaterThanOrEqualOrNull The value of {resource attribute name} in question is null or it is greater than or equal to the specified value Resource field name expected to be type of number
{resource attribute name}Equal The value of {resource attribute name} in question is equal to the specified value Resource field name expected to be type of number or string
{resource attribute name}Like The value of {resource attribute name} in question contains the specified value string Resource field name expected to be type of string
{resource attribute name}MultiLikeOr The value of {resource attribute name} in question TBD Resource field name expected to be type of string
{resource attribute name}MultiLikeAnd The value of {resource attribute name} in question TBD Resource field name expected to be type of string
{resource attribute name}EndsWith The value of {resource attribute name} in question ends with the specified string value Resource field name expected to be type of string
{resource attribute name}StartsWith The value of {resource attribute name} in question starts with the specified string value Resource field name expected to be type of string
{resource attribute name}In The value of {resource attribute name} in question is one of the values that specified in the comma seperated specified string value Resource field name expected to be type of number or string
{resource attribute name}NotIn The value of {resource attribute name} in question is not one of the values that specified in the comma seperated specified string value Resource field name expected to be type of number or string
{resource attribute name}NotEqual The value of {resource attribute name} in question Resource field name expected to be type of number or string
{resource attribute name}BitAnd The bit AND operation of the value of {resource attribute name} in question and the specified value != 0 Resource field name expected to be type of number
{resource attribute name}BitOr The bit OR operation of the value of {resource attribute name} in question and the specified value != 0 Resource field name expected to be type of number
{resource attribute name}MatchOr The value of {resource attribute name} in question TBD Resource field name expected to be type of string
{resource attribute name}NotContains The value of {resource attribute name} in question not contains the soecified string value Resource field name expected to be type of string
{resource attribute}Empty The value of {resource attribute name} in question Resource field name expected to be type of number or string

In case that "filter" is not presented as argument of list action, the list expected to include all the resources in question (the actual response depends on the requested page/size)

KalturaFilter is an abstract generic class.

Generic class shall include "x-template" field that defines the generic/template type parameters - dictionary of one or more template's parameters (key) to its list of constraints (values)

→ Click to expand KalturaFilter formal definition... 
    KalturaFilter:
      description: |-
        Kaltura  base filter.
      type: object
      # x-template defines the template/generic type parameters - dictionary of one or more template's parameters (key) to its list of constraints (values))
      x-template:
        # The type parameter is FilterT and it should satisfy all the interfaces in the array (C# where constraints )
        FilterT: ["struct", "IComparable", "IFormattable", "IConvertible"]
      allOf:
      - $ref: '#/components/schemas/KalturaOTTObject'
      - type: object
        properties:
          orderBy:
            type: object
            # Defines the object type as a template parameter type
            x-templat-type: FilterT

    KalturaReminderFilter:
      description: |-
        Kaltura remainder base filter.
      type: object
      # x-template defines the template/generic type parameters - dictionary of one or more template's parameters (key) to its list of constraints (values))
      x-template:
        # The type parameter is ReminedFilterT and it should satisfy all the interfaces in the array (C# where constraints )
        ReminedFilterT: ["struct", "IComparable", "IFormattable", "IConvertible"]
      allOf:
      - $ref: '#/components/schemas/KalturaFilter'
        # Assign the template parameters values
        x-template-instantiation:
          # FilterT is populated with ReminedFilterT
          FilterT: ReminedFilterT

      - type: object
        properties:
          ksql:
            type: string

Any class that inherits KalturaFilter shall instantiate its template parameters using the x-template-instantiation field that defines value per template parameter.

→ Click to expand KalturaReminderFilter - example of abstract filter tht is inherited from KalturaFilter... 
    KalturaReminderFilter:
      description: |-
        Kaltura remainder base filter. 
      type: object
      # x-template defines the template/generic type parameters - dictionary of one or more template's parameters (key) to its list of constraints (values))
      x-template: 
        # The type parameter is ReminedFilterT and it should satisfy all the interfaces in the array (C# where constraints )
        ReminedFilterT: ["struct", "IComparable", "IFormattable", "IConvertible"]
      allOf:
      - $ref: '#/components/schemas/KalturaFilter'
        # Assign the template parameters values
        x-template-instantiation:
          # FilterT is populated with ReminedFilterT
          FilterT: ReminedFilterT

      - type: object
        properties:
          ksql: 
            type: string

A concrete Kaltura Filter is inherited from KalturaFilter or from one of its inherited class.

A concrete filter class shall define its default orderBy value.

Note that the orderBy enum MUST be defined as a Kaltura standard enum type and the orderBy field shall reffer to it (via ollOf)

→ Click to expand KalturaAssetReminderFilter - example of concret filter that is inherited from KalturaFilter... 
    KalturaAssetReminderFilter:
      description: |-
        Kaltura asset remainder 
      type: object
      allOf:
      - $ref: '#/components/schemas/KalturaReminderFilter'

        # Assign the template parameters values
        x-template-instantiation:
          # ReminedFilterT is populated with KalturaAssetReminderOrderBy
          ReminedFilterT: "#/components/schemas/KalturaAssetReminderOrderBy"
      - type: object
        properties:
          # orderBy is defined with reference to enume object and with it default value
          orderBy: 
            # defalt value is defined to overide its ancestore default. 
            x-override-default: true
            default: RELEVANCY_DESC
            # x-get-default-orderby defines that GetDefaultOrderBy shall be implemented and its return  type
            x-get-default-orderby: "#/components/schemas/KalturaAssetReminderOrderBy"
            allOf:
              - $ref: '#/components/schemas/KalturaAssetReminderOrderBy'

KalturaPager

Phoenix list action expected two arguments "filter" and "pager".

"pager" is used to specify what resources will be part of the actual response, out of all the resources that were filtered by the "filter" argument criteria (see KalturaFilter section).

Pager characteristics

  • "pager" argument specify what indexes of resorces shall be part of the response

  • The resource index is defined by the filter and its defined order,

  • pager attribute shall be type of KalturaFilterPager that includes two attributes:

    • pageIndex

    • pageSize

  • For pageIndex X and pageSize Y the response shall include resources from [(X-1) * Y] to [X * Y] (if exists) The default behavior:

    1. Max pageSize == 500

    2. Default pageSize is 30 (used if the pageSize omitted or less than 1)

    3. Default page index is 1

    4. If provided pageSize greater than 500 then 500 will be set

  • In case that "pager" is not presented as argument of list action, the list expected to include the first 25 resources

→ Click to expand KalturaPager formal definition... 
KalturaFilterPager:
  description: >-
    The KalturaFilterPager object enables paging management to be applied upon
    service list actions
  type: object
  x-namespace: WebAPI.Models.General
  allOf:
    - $ref: ott-schema-registry/models/api/rest/kalturaOTTObject
    - properties:
        pageSize:
          type: integer
          format: int32
          description: >-
            <![CDATA[The number of objects to retrieve. Possible range 1 ≤ value ≤
            500\. If omitted or value < 1 - will be set to 30\. If a value > 500
            provided -- will be set to 500]]>
          nullable: true
          minimum: 1
          maximum: 500
          default: 30
        pageIndex:
          type: integer
          format: int32
          description: The page number for which {pageSize} of objects should be retrieved
          nullable: true
          minimum: 1
          default: 1

Phoenix Response Structure

An action response includes:

  1. "executionTime" - the execution time in seconds.

  2. "result" - one of two objects:

    1. Success results as defined by the action in question

    2. Error result - instance of KalturaAPIException

    1. Error result - instance of KalturaAPIException
→ Click to expand response structure - generic example... 
ServiceNameActionNameResponse:
  type: object
  description: >-
    ServiceNameActionName respone.

    The response includes its execution time and the result,

    Result can be success object as defined per action or one of pre-defined
    KalturaAPIException values.
  x-object-type: phoenix-response
  properties:
    executionTime:
      type: integer
      description: Execution time
    result:
      oneOf:
        - $ref: '#/components/schemas/ActionNameSuccessResponse'
        - $ref: '#/components/schemas/KalturaServiceNameActionNameException'
      type: object
ActionNameSuccessResponse:
  type: object
  title: Success Respones
  description: Seccess response for actionName
KalturaServiceNameActionNameException:
  description: >-
    list of valid KalturaAPIException that could be thrown by actionName of
    serviceName.
  type: object
  properties:
    error:
    # To enable reuse of the enum objects and nice presentation, error is modeled as one of list of error objects.
    # Eatch error object is enume with one and only one value
      oneOf:
        - $ref: '#/components/schemas/KalturaAPIExceptionInstanceOne'
        - $ref: '#/components/schemas/KalturaAPIExceptionInstanceTwo'
        - $ref: '#/components/schemas/KalturaAPIExceptionInstanceThree'
        - $ref: '#/components/schemas/KalturaAPIExceptionInstanceFour'
        - $ref: '#/components/schemas/KalturaAPIExceptionInstanceFive'

Phoenix error responses includes the following headers:

  1. "key":"X-Kaltura-Error-Code"; "value":"{Kaltura error code}"
  2. "key":"X-Kaltura-Error-Msg"; "value":"{Kaltura error message}"
  3. "key":"X-Kaltura-Error-Name"; "value":"{Kaltura error name}"

KalturaListResponse

Phoenix error responses includes the following headers:

  1. "key":"X-Kaltura-Error-Code"; "value":"{Kaltura error code}"

  2. "key":"X-Kaltura-Error-Msg"; "value":"{Kaltura error message}"

  3. "key":"X-Kaltura-Error-Name"; "value":"{Kaltura error name}"

KalturaListResponse

Different Phoenix actions (mainly list action of each of the supported services), response with list of resources. All the Phoenix actions that return list of resources shall be inherited from a common ancestor KalturaListResponse.

List response characteristics

  • List response includes two attributes "totalCount" and "objects"

  • totalCount is populated with the total number of requested items without taking uder consideration pagination

  • objects is an array of objects that shall be populated with the response items - the object field is expected to be overwritten by the inheritted schema that shall specify the concreet response object type

→ Click to expand kalturaListResponse formal definition... 
KalturaListResponse:
  x-namespace: WebAPI.Models.General
  allOf:
    - $ref: ott-schema-registry/models/api/rest/kalturaOTTObject
    - $ref: ott-schema-registry/models/api/rest/iKalturaListResponse
    - type: object
      properties:
        totalCount:
          type: integer
          format: int32
          description: Total items (the actual respone won't include mire than totalCount entities but might include less if e.g. the requested page size is smaller then totalCount)
          x-validation-exception: NULLABLE

KalturaAPIException

Phoenix API errors should be presented as KalturaAPIException.

API exception characteristics

  • API exception includes three attributes "message", "code" and "args"

  • code is populated with unique error code

  • message is populated with relevant message that can include arguments

  • args is populated with the message arguments

Phoenix API errors should be presented as KalturaAPIException.

API exception characteristics API exception includes three attributes “message", "code" and “args“

code is populated with unique error code

message is populated with relevant message that can include arguments

args is populated with the message arguments

→ Click to expand KalturaApiExceptionArg formal definition... 
KalturaApiExceptionArg:
  type: object
  description: Kaltura API Exception Arg
  x-namespace: WebAPI.Models.General
  required:
    - name
    - value
  properties:
    name:
      type: string
      minLength: 1
      maxLength: 50
      description: The arg name
    value:
      type: string
      minLength: 1
      maxLength: 255
      description: The arg value

A response suggest one of list of concrete KalturaAPIException, meaning a KalturaAPIException enum object wit hone value.

→ Click to expand a valid response error list... 
.
                              .
                              .
# Error list definition
            error:
                oneOf:
                    - $ref: '#/components/schemas/KalturaAPIExceptionOne'
                    - $ref: '#/components/schemas/KalturaAPIExceptionTwo'
                    - $ref: '#/components/schemas/KalturaAPIExceptionThree'
                    - $ref: '#/components/schemas/KalturaAPIExceptionFour'
                    - $ref: '#/components/schemas/KalturaAPIExceptionFive'
                    .
                    .
                    .
# The error objects definitions
KalturaAPIExceptionOne:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4021
          name: InvalidAssetType
          message: The asset requested is not a valid asset type
    KalturaAPIExceptionTwo:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4098
          name: InvalidAssetStruct
          message: Invalid asset struct
    KalturaAPIExceptionThree:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 2038
          name: TopicNotFound
          message: TopicNotFound
    KalturaAPIExceptionFour:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4033
          name: MetaDoesNotExist
          message: The specified meta id does not exist
    KalturaAPIExceptionFive:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4099
          name: NoNextEpisode
          message: User have not started watching this TV series

Phoenix API Features

Alias

To enable migration of partners from legacy asset models to asset, as it is modelled in OPC, and resolve metas and tags 'system name' conflicts, alias, as alternative to aset's metas and tags 'system names' was added.

Alias enables operator to configure aliases to, asset.metas and asset.tags keys, and configure who get as response to asset.get and asset.list, instead of asset.metas and asset.tag keys' systemName, its alias.

For details see KalturaCustomFieldsPartnerConfiguration, KalturaUserRoleProfile, KalturaAssetStruct, KalturaMeta, KalturaAssetStructMeta

Multi request service

Multi request service enables to execute list of service actions one after the other.

Multi request service is depricated and shall not be used - exceptions shall be approved by Kaltura. It is recommended to use Experience API (GraphQL) as alternative to multirequest service!

Response profile

Response profile enables API callers to request to enrich the response with additional related data or to clean it from unnecessary data.

Response profile is supported only for specific objects/profiles

It is recommended to use Experience API (GraphQL) as alternative to response profile feature - Experience API provides full flexibility and richer capabilities!

Roles and permissions

KTP supports roles and permissions, and enables partners to define custom roles and associate it with users.

  1. Any KTP user is associated with zero or more roles.

    1. A role is associated with permission/s

      1. Permission can be included or excluded for specific role

      2. Excluded permission has always higher prioerity than included permission

    2. Permission is a set of permission items that define an atomic permission to use specific service, action or attribute

  2. User that is associated with role, is granted to all the permissions/permission items that are associated with the role in question (1.a.ii resolves any conflict)

    1. User has permission only to activities that he is granted by (2) - only included permissions that were not excluded by any of the roles that are associated to the user in question.

  3. User's role/s are embedded in his session (KS) - User's role/s updates will impact only calls with updated KS.

  4. PermissionItem cannot be updated via API (require Phoenix configuration changes)

For more details see permission service, KalturaPermission, permissionItem service, KalturaPermissionItem, KalturaApiParameterPermissionItemAction, KalturaPermissionType, userRole service, KalturaUserRole, ottUser.addRole

Sort by priority groups

Sorting the results is defined by one of the filter order arguments.

A special filter property named shouldApplyPriorityGroupsEqual enables the coller to use predefined (per partner/group) main sort that that is based on the partner priority groups order as it defined by:

  1. searchPriorityGroup

  2. searchPriorityGroupOrderedIdsSet

For details see searchPriorityGroup service, KalturaSearchPriorityGroup, searchPriorityGroupOrderedIdsSet service, KalturaSearchPriorityGroupOrderedIdsSet

Phoenix service/action End to End Examples

Generic example

The following example presents an OpenAPI Phoenix service/action definition of generic request and response example.

→ Click to expand the example - JSON representation... 
openapi: 3.0.0
servers:
  - description: Kaltura REST API server.
    url: https://openapi.kaltura.com/components/1.0.0
info:
  version: x.y.z
  title: serviceExample.actionExample
  contact:
    email: shai.gotlib@kaltura.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: serviceExampleActionExample
    description: End to end example of service with one action
paths:
  /service/serviceExample/action/actionExample:
    description: Example of end to end actionExample of service Example
    post:
      summary: ''
      operationId: post-serviceexample-actionexample
      description: Return response of ServiceObject of actionExample.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/OTTRequest'
                - type: object
                  description: actionExample arguments
                  properties:
                    actionExampleArgs:
                      $ref: '#/components/schemas/KalturaActionExampleArgs'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  executionTime:
                    type: number
                    description: Execution time
                  result:
                    oneOf:
                      - $ref: '#/components/schemas/KalturaServiceExample'
                      - type: object
                        properties:
                          error:
                            oneOf:
                              - $ref: '#/components/schemas/KalturaAPIExceptionOne'
                              - $ref: '#/components/schemas/KalturaAPIExceptionTwo'
                              - $ref: '#/components/schemas/KalturaAPIExceptionThree'
                              - $ref: '#/components/schemas/KalturaAPIExceptionFour'
                              - $ref: '#/components/schemas/KalturaAPIExceptionFive'
components:
  schemas:
    OTTRequest:
      description: Common part of any response (such as KS, version, etc.)
      type: object
    KalturaActionExampleArgs:
      type: object
      description: Arguments for actionExample.
    KalturaServiceExample:
      description: ServiceExample resource
      type: object
    KalturaAPIExceptionOne:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4021
          name: InvalidAssetType
          message: The asset requested is not a valid asset type
    KalturaAPIExceptionTwo:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4098
          name: InvalidAssetStruct
          message: Invalid asset struct
    KalturaAPIExceptionThree:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 2038
          name: TopicNotFound
          message: TopicNotFound
    KalturaAPIExceptionFour:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4033
          name: MetaDoesNotExist
          message: The specified meta id does not exist
    KalturaAPIExceptionFive:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4099
          name: NoNextEpisode
          message: User have not started watching this TV series
    KalturaAPIException:
      type: object
      description: Ancestor of all Kaltura API exceptions
      x-namespace: WebAPI.Models.General
      required:
        - objectType
        - code
        - name
      properties:
        objectType:
          type: string
        code:
          type: integer
          format: int32
          description: Error code
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: Error name
        message:
          type: string
          description: Error message
          nullable: true
          maxLength: 255
        description:
          type: string
          description: Error description
          nullable: true
          maxLength: 255
        args:
          type: array
          description: Array of message's arguments
          items:
            $ref: '#/components/schemas/KalturaApiExceptionArg'
    KalturaApiExceptionArg:
      type: object
      description: Kaltura API Exception Arg
      x-namespace: WebAPI.Models.General
      required:
        - name
        - value
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: The arg name
        value:
          type: string
          minLength: 1
          maxLength: 255
          description: The arg value

Legacy form example

The following example presents an OpenAPI Phoenix service/action definition that includes legacy request form.

The selected service name is assetHistory and the action is getNextEpisode.

The action gets as input request object that is compounded of three objects/set of arguments:

  1. OttObjects common arguments.

  2. List of dedicated required arguments that common to all getNextEpisode requests.

  3. One of two alternative that shall be included in the request.

The response is either success object or an error (KalturaAPIException instance)

→ Click to expand assetHistory.getNextEpisode - Legacy form of action example - JSON representation... 
openapi: 3.0.0
servers:
  - description: Kaltura REST API server.
    url: https://openapi.kaltura.com/components/1.0.0
info:
  version: x.y.z
  title: assetHistory.getNextEpisode
  contact:
    email: shai.gotlib@kaltura.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: assetHistoryGetNextEpisode
    description: >-
      Return next episode asset to watch, based on the caller's last watched,
      series in question episode.

      ## Limitations and assumptions:

      1\. It is assumed that the maximum episodes in season is
      MAX_EPISODE_IN_SEASON == 100,000

      2\. The next episode, the first and the last one shall be based on the
      episodes order as it defined by the following calculation:

          MAX_EPISODE_IN_SEASON * {seasonNumber} + {episodeNumber}
      3\. If {seasonNumber} is undefined then it is considered 0 (zero)

      ## Calculate the return value:

      1\. If no VOD episode from the series was watched then:

        1.1 If (notWatchedReturnStrategy == RETURN_FIRST_EPISODE) then the first VOD episode in the series shall be return

        1.2 If (notWatchedReturnStrategy == RETURN_NO_NEXT_EPISODE) thenresponse with eResponseStatus.NoNextEpisode
      2\. If a VOD episode from the series was watched then the last watched VOD
      episode in the series in question is "the episode of choice":

        2.1 If the episode of choice completely was watched then reply with the next VOD episode to watch.

          2.1.1 If there is no next VOD episode to watch in the series in question then:

            2.1.1.1 If (watchedAllReturnStrategy == RETURN_FIRST_EPISODE) then return the first existing VOD episode in the series in question.
            2.1.1.2 If (watchedAllReturnStrategy == RETURN_LAST_EPISODE) then return the last existing VOD episode in the series in question.
            2.1.1.3 If (watchedAllReturnStrategy == RETURN_NO_NEXT_EPISODE) thenresponse with eResponseStatus.NoNextEpisode
        2.2 If the episode of choice wasn't completely watched then reply with the episode of choice.

      **Assumptions**

      1\. There are maximum 100,000 episodes per season (episode number <
      100,000)

      2\. There ar maximum 10,000 season per series (season number < 10,000)
paths:
  /service/assetHistory/action/getNextEpisode:
    description: >-
      Return next episode asset to watch, based on the caller's last watched,
      series in question episode.
    post:
      summary: ''
      operationId: post-assethistory-getnextepisode
      description: >-
        Return next episode asset to watch, based on the caller's last watched,
        series in question episode.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/OTTRequest'
                - type: object
                  description: >-
                    Defines common request arguments for all
                    KalturaAssetHistoryGetNextEpisodeRequest.

                    Note: inherited from OTTRequest
                  properties:
                    notWatchedReturnStrategy:
                      $ref: '#/components/schemas/KalturaNotWatchedReturnStrategy'
                    watchedAllReturnStrategy:
                      $ref: '#/components/schemas/KalturaWatchedAllReturnStrategy'
                - type: object
                  oneOf:
                    - type: object
                      properties:
                        assetId:
                          type: string
                          description: 'The asset identifier in question. '
                      required:
                        - assetId
                    - type: object
                      properties:
                        seriesId:
                          type: string
                          description: 'The series identifier in question. '
                      required:
                        - seriesId
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  executionTime:
                    type: number
                    description: Execution time
                  result:
                    oneOf:
                      - $ref: '#/components/schemas/KalturaAssetHistory'
                      - type: object
                        properties:
                          error:
                            oneOf:
                              - $ref: '#/components/schemas/InvalidAssetType'
                              - $ref: '#/components/schemas/InvalidAssetStruct'
                              - $ref: '#/components/schemas/TopicNotFound'
                              - $ref: '#/components/schemas/MetaDoesNotExist'
                              - $ref: '#/components/schemas/NoNextEpisode'
components:
  schemas:
    OTTRequest:
      description: Common part of any response (such as KS, version, etc.)
      type: object
    KalturaNotWatchedReturnStrategy:
      type: string
      enum:
        - RETURN_NO_NEXT_EPISODE
        - RETURN_FIRST_EPISODE
      default: RETURN_NO_NEXT_EPISODE
      description: >-
        A policy to define the return value when user watched no episode exists
        in series.
    KalturaWatchedAllReturnStrategy:
      type: string
      enum:
        - RETURN_NO_NEXT_EPISODE
        - RETURN_FIRST_EPISODE
        - RETURN_LAST_EPISODE
      default: RETURN_LAST_EPISODE
      description: >-
        A policy to define the return value when user finished to watch the last
        episode exists in series.
    KalturaAssetHistory:
      description: 'Watch history asset info. '
      type: object
    InvalidAssetType:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4021
          name: InvalidAssetType
          message: The asset requested is not a valid asset type
    InvalidAssetStruct:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4098
          name: InvalidAssetStruct
          message: Invalid asset struct
    TopicNotFound:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 2038
          name: TopicNotFound
          message: TopicNotFound
    MetaDoesNotExist:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4033
          name: MetaDoesNotExist
          message: The specified meta id does not exist
    NoNextEpisode:
      allOf:
        - type: object
          $ref: '#/components/schemas/KalturaAPIException'
      enum:
        - code: 4099
          name: NoNextEpisode
          message: User have not started watching this TV series
    KalturaAPIException:
      type: object
      description: Ancestor of all Kaltura API exceptions
      x-namespace: WebAPI.Models.General
      required:
        - objectType
        - code
        - name
      properties:
        objectType:
          type: string
        code:
          type: integer
          format: int32
          description: Error code
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: Error name
        message:
          type: string
          description: Error message
          nullable: true
          maxLength: 255
        description:
          type: string
          description: Error description
          nullable: true
          maxLength: 255
        args:
          type: array
          description: Array of message's arguments
          items:
            $ref: '#/components/schemas/KalturaApiExceptionArg'
    KalturaApiExceptionArg:
      type: object
      description: Kaltura API Exception Arg
      x-namespace: WebAPI.Models.General
      required:
        - name
        - value
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 50
          description: The arg name
        value:
          type: string
          minLength: 1
          maxLength: 255
          description: The arg value

Filter end to end example

KalturaFilter is an abstract generic class. To constract KalturaFilter, its generic/template parameter (TFilterT) shall be resolved.

The following example presents two level of inheritance:

  1. KalturaReminderFilter inherits KalturaFilter

  2. KalturaAssetReminderFilter, KalturaSeriesReminderFilter and KalturaSeasonsReminderFilter inherits KalturaReminderFilter

→ Click to expand reminder.list - OpenAPI YAML code example... 
openapi: 3.0.0
servers:
  - description: Kaltura REST API server.
    url: https://openapi.kaltura.com/components/1.0.0
info:
  version: x.y.z
  title: reminder.liste
  contact:
    email: shai.gotlib@kaltura.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
tags:
  - name: reminderList
    description: |-
      reminder/action/list to present template/generic filters definitions
paths:
  /service/reminder/action/list:
    description: Return list of reminders
    post:  
      summary: ''
      operationId: post-reminder-list
      description: Return list of reminders.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/KalturaReminderFilter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  executionTime:
                    type: number
                    description: Execution time
                  result:
                    oneOf:
                      - $ref: '#/components/schemas/KalturaReminderListResponse'
                      - type: object
                        properties:
                          error:
                            $ref: '#/components/schemas/KalturaAPIException'
components:
  schemas:
    KalturaAPIException:
      title: Kaltura API Exception
      description: Kaltura API exception
    OTTRequest:
      description: |-
        Common part of any response (such as KS, version, etc.)
      type: object
    KalturaReminderListResponse:
      type: object
      description: |-
          Kaltura Reminder List Response

    KalturaOTTObject:
      description: |-
        Kaltura  base object. 
      type: object
    KalturaFilter:
      description: |-
        Kaltura  base filter. 
      type: object
      # x-template defines the template/generic type parameters - dictionary of one or more template's parameters (key) to its list of constraints (values))
      x-template: 
        # The type parameter is FilterT and it should satisfy all the interfaces in the array (C# where constraints )
        FilterT: ["struct", "IComparable", "IFormattable", "IConvertible"]
      allOf:
      - $ref: '#/components/schemas/KalturaOTTObject'
      - type: object
        properties:
          orderBy: 
            type: object
            # Defines the object type as a template parameter type
            x-templat-type: FilterT

    KalturaReminderFilter:
      description: |-
        Kaltura remainder base filter. 
      type: object
      # x-template defines the template/generic type parameters - dictionary of one or more template's parameters (key) to its list of constraints (values))
      x-template: 
        # The type parameter is ReminedFilterT and it should satisfy all the interfaces in the array (C# where constraints )
        ReminedFilterT: ["struct", "IComparable", "IFormattable", "IConvertible"]
      allOf:
      - $ref: '#/components/schemas/KalturaFilter'
        # Assign the template parameters values
        x-template-instantiation:
          # FilterT is populated with ReminedFilterT
          FilterT: ReminedFilterT

      - type: object
        properties:
          ksql: 
            type: string


    KalturaAssetReminderFilter:
      description: |-
        Kaltura asset remainder 
      type: object
      allOf:
      - $ref: '#/components/schemas/KalturaReminderFilter'

        # Assign the template parameters values
        x-template-instantiation:
          # ReminedFilterT is populated with KalturaAssetReminderOrderBy
          ReminedFilterT: "#/components/schemas/KalturaAssetReminderOrderBy"
      - type: object
        properties:
          # orderBy is defined with reference to enume object and with it default value
          orderBy: 
            # defalt value is defined to overide its ancestore default. 
            x-override-default: true
            default: RELEVANCY_DESC
            # x-get-default-orderby defines that GetDefaultOrderBy shall be implemented and its return  type
            x-get-default-orderby: "#/components/schemas/KalturaAssetReminderOrderBy"
            allOf:
              - $ref: '#/components/schemas/KalturaAssetReminderOrderBy'


    KalturaAssetReminderOrderBy:
      description: |-
        Kaltura asset remainder enum:
      type: string
      enum:
      - RELEVANCY_DESC
      - NAME_ASC 
      - VIEWS_DESC  
      - RATINGS_DESC 
      - VOTES_DESC 
      - START_DATE_DESC 
      - START_DATE_ASC 
      - LIKES_DESC  

    KalturaSeriesReminderFilter:
      description: |-
        Kaltura series remainder 
      type: object
      allOf:
      - $ref: '#/components/schemas/KalturaReminderFilter'
        # Assign the template parameters values
        x-template-instantiation:
          # ReminedFilterT is populated with KalturaSeriesReminderOrderBy
          ReminedFilterT: "#/components/schemas/KalturaSeriesReminderOrderBy"
      - type: object
        properties:
          orderBy: 
            # defalt value is defined to overide its ancestore default. 
            x-override-default: true
            default: NONE
            # x-get-default-orderby defines that GetDefaultOrderBy shall be implemented and its return  type
            x-get-default-orderby: "#/components/schemas/KalturaAssetReminderOrderBy"
            allOf:
              - $ref: '#/components/schemas/KalturaSeriesReminderOrderBy'
          seriesIdIn: 
            type: string
          epgChannelIdEqual: 
            type: integer

    KalturaSeriesReminderOrderBy:
      description: |-
        Kaltura series remainder enum:
      type: string
      enum:
      - NONE


    KalturaSeasonsReminderFilter:
      description: |-
        Kaltura season remainder 
      type: object
      allOf:
      - $ref: '#/components/schemas/KalturaReminderFilter'
        # Assign the template parameters values
        x-template-instantiation:
          # ReminedFilterT is populated with KalturaSeriesReminderOrderBy
          ReminedFilterT: "#/components/schemas/KalturaSeriesReminderOrderBy"
      - type: object
        properties:
          orderBy: 
            # defalt value is defined to overide its ancestore default. 
            x-override-default: true
            default: NONE
            # x-get-default-orderby defines that GetDefaultOrderBy shall be implemented and its return  type
            x-get-default-orderby: "#/components/schemas/KalturaAssetReminderOrderBy"
            allOf:
              - $ref: '#/components/schemas/KalturaSeriesReminderOrderBy'
          seasonNumberIn: 
            type: string
          seriesIdEqual: 
            type: string
          epgChannelIdEqual: 
            type: integer