The Kaltura API Client Library Generator is an automatic method of packaging the native API client libraries from the latest API code. The Kaltura Server provides a unique way of generating an always up-to-date native API Client Libraries by using an XML based reflection of Kaltura's internal API classes (API services, actions, objects, Enums...).
The updated version of the API description can be retrieved at the following URL: http://www.kaltura.com/api_v3/api_schema.php
By parsing the schema.xml file, it is possible to construct the complete structure of the objects in the system. A generic template to parse the schema file was created to ease the process of creating new parsers. The TemplateClientGenerator is a basic template for creating a custom client library generator, by providing the following:
- A high-level parsing of class types: Enums, Objects and Services (implemented in the generate() function).
- A template of parsing functions to be overriden or replaced by the actual parser implementation to create the client library of the target programming language.
The schema structure
The schema is divided to three main sections:
- Enums - Constants and Types defined and used by the system.
- Classes - Objects (VO - Value Objects) defined and used by the system.
- Services - The Services and Actions defined and exposed by the system API to manipulate the Objects.
Every node defines a respective part of the system (whether enum, class or service) and provides the following information:
- Enums - Define name and value of the constant properties of the enum class.
- Classes - Define name, variable type (string, int, etc.), if the property is readOnly (read) or insertOnly (write) and description of the class and it's uses.
- Services -Define a list of actions available, the parameters sent required by the action, the service and actions description and uses.
Creating a custom client library generator
To create your own customized Automatic Kaltura API Client Library, download the TemplateClientGenerator project.
The TemplateClientGenerator project includes the following files:
- ClientGeneratorFromXml.php - Abstract class extended by the TemplateClientGenerator, provides base helper functions.
- generate_client.php - Wrapper script to run the generator and test the client library creation - this class saves the files generated by the TemplateClientGenerator class to the disk.
- TemplateClientGenerator.php - The Client Library Generator script, this class parses the API reflection xml schema and create the client library files contents.
- writeEnum - Parses Enum (aka. types) classes.
- writeObjectClass - Parses Object (aka. VO) classes.
- writeService - Parses Services and actions (calls that can be performed on the objects).
- writeMainClass - Create the main class of the client library, may parse Services and actions.
- writeProjectFile - Create the project file (if needed).
At the end of every function un-comment the following line:
$this->addFile('path to new file', 'file contents');
For every file you want to create in the generator, call the method addFile. The addFile method adds all the files you have created into an Array, which will then be saved to disk to create your client library.
The ClientGeneratorFromXml also provides the following helper functions to ease development:
- setParam / getParam - An interface to add custom parameters during generation (this can be used to create configurable client libraries, e.g. the flash and flex client libraries are generated from the same generator class, by default it creates the flash library, however, when passing a parameter 'type' with value of 'flex_client' the generator will create a Flex library).
- endsWith - Test if a given string ends with another string.
- beginsWith - Test if a given string starts with another string.
The PHP Reflection Generator
In addition to the method of using the schema XML, there is also a method of creating a Client Library Generator by extending the ClientGeneratorFromPhp class. The ClientGeneratorFromPhp class provides a reflection mechanism that doesn't require the step of creating or downloading the schema xml. However, this method requires that the full server will be deployed and configured. This method should be treated as deprecated and avoided.