This document was written to provide a basic introduction to the Kaltura TestMe Console - A tool that provides interaction with Kaltura API calls using a simple user interface.
There are two versions to the Kaltura API, Partner Services 2 and 3, also known by the name api_v2 and api_v3.
Respectively, there are two versions of the TestMe Console. The api_v2 TestMe , which works with Version 2 of the API (api_v2), and api_v3 TestMe that is also a part of KalturaCE and is the recommended version of the API to use (api_v2 will be deprecated over time).
Partner Services 2 vs Partner Services 3 (or api_v2 vs. api_v3)
api_v3 was designed to provide an OOP approach to Kaltura objects and services -
In api_v2 services were called by their's name, for example: getentry was used to retrieve any entry on the system whether mix, media, document, etc.
In api_v3 there is an hierarchy; Services represent the objects in the system. Services contain actions, and there is a clear separation between object types. For example, in api_v3 to retrieve an entry you should call the get action on the type of service you require (media, mix, baseEntry, etc.) - i.e. to retrieve a media type entry - call media.get and to retrieve a mix entry call mixing.get .
A Kaltura Session (aka KS), represents the validation required to authenticate the user calling/performing the action API - this is the same in both api_v2 and api_v3.
The KS is used to authenticate a user to provide a security model that can:
- Associate content with specific user and limit access from other users
- Provide moderation control
- Enable restriction of global content only to site administrator (i.e. actions like list can expose all content a partner has in the system)
- Provide a security model for limiting bandwidth usage, streaming of media and access to metadata and files
The KS is generated as a mixture of the following information -
- The Partner ID (and sub partner id)
- The User ID
- The secret (this is obtained upon registration or installation of CE), an administrator secret is used to create an ADMIN type KS while the user secret is used to generate a limited regular user session
- Time of creation and expiration time (When the time period expires - the KS is no longer valid and you should create a new one)
- The type of session (ADMIN or USER)
- The privileges assigned to the session. If the user should have edit privileges on mixes, pass the following value - edit:* (edit privileges = The user will be able to save a mix using setmetadata or mixing.update API)
There are subtle differences in the session protocol between api_v2 and api_v3 -
- api_v2 requires all identification parameters to be sent, such as partner id, subpid, user id, etc. on all api calls. However in api_v3, you pass all the identification parameters once to the session.start action and then only pass the KS parameter for the rest of the api calls. This is because the KS already holds this information.
- There are two types of KalturaSessionType in the system - USER and ADMIN. In api_v2 a subset of the services can be performed only by the ADMIN, another subset can be performed only by the USER and a few can be performed without authentication (non-secured), while there was a special ADMIN type (admin=2) that allows all actions to be performed. api_v3 changes this permissions protocol - in api_v3, there are still two types of KalturaSessionType, ADMIN and USER, though an ADMIN is an absolute administrator and can call / perform all actions in the system while the USER type can only perform a subset that is relevant for a user in the system.
- In the api_v2 TestMe Console, the API actions that require an ADMIN type KS where marked with orange background color while regular USER type actions marked with green background color. in api_v3 ADMIN can perform all actions, and so there is no color separation. To know what services require ADMIN type KS, refer to the API documentation.
Working with api_v2 TestMe Console for the First Time
- Open the TestMe Console in your browser.
- Enter your Partner ID in the partner_id text field (screenshot). This information can be found in the introductory e-mail that you received when you signed up to Kaltura or installed the KalturaCE. The partner information is also available in the Server tab inside the KMC. For further information refer to the How to Obtain Partner Identifiers guide.
- Enter your Sub Partner ID in the subp_id text field (screenshot).
- In the service drop down menu select start session (screenshot). You'll notice that when you select the start session option that the text area now becomes a light blue. The TestMe console is color coded to help you work out what you can and cannot do. Light Blue refers to API calls that do not require a session. Green means you must have a USER type session. Orange means you must have an ADMIN type session.
- In the secret field enter your admin secret as found in the welcome e-mail (screenshot). For the purposes of this introduction, we will log in with administrator rights (ADMIN type KS), however it's important to note that not all features will work in this mode. In api_v2 some API calls require user rights (USER type KS), or in api_v2 we can also create a complete ADMIN by passing admin=2 (see below).
- In the admin field enter "1" (screenshot). (In most coding languages the number one refers to true/yes, whereas zero refers to false/no.)
- Press the submit button (screenshot).
- If you entered the right partner identifier values, you should get this result . The left KS text box will show a string of random characters, and the result box to the right will show something similar to the following:
- If you do not see this result, double check the partner details you entered. Alternatively, if the result area looks like the above, but there is nothing in the KS textbox (can happen on opera/safari) - manually copy and paste the KS result from the XML data on the right to the KS text box on the left (screenshot).
- Now that you have obtained a KS you can call the rest of the API actions. For example, select list entries from the service drop down list and press submit. This will return a list of the entries (media files, mixes, documents, etc.) you have.
Working with api_v3 TestMe Console for the First Time
api_v3 also comes with a new TestMe Console. You will notice some changes in UI and design, created to provide is a simpler console. One of the useful additions is the history drop down which document all the previous API calls you have made in that session. To create a KS and start working -
- Select session from the Select Service drop down list.
- Insert your admin secret in the secret (string) text box.
- Select ADMIN from the type (KalturaSessionType) drop down list.
- Insert your Partner ID in the partnerId (int) text box. You'll notice that you no longer need to enter your sub-partner ID (there is no subpid in api_v3).
- Click the Send button.
- If you entered the right partner identifiers values the KS field will show a string of random characters. Now you can proceed to performing API actions. It's also important to note that as of api_v3, administrators can now do everything that a user can do, so be careful! - Do not expose your ADMIN KS to the public, only the user KS.
- For more information about using api_v3 refer to the Kaltura API (api_v3) - Getting started guide.
- For further information on the API calls for Partner Services 2 (api_v2), please refer to the old wiki - Please note that api_v2 is deprecated and should be avoided.
- For further information on the API calls for Partner Services 3 (api_v3), please refer to the api_v3 API documentation.
- When you are ready for deployment, you can use one of the client libraries to easily perform the API callbacks in your programming language of choice - Refer to the Kaltura API Client Libraries Guide for more.