README

This PHP composer package is meant to provide a unified easy-to-use Opencast RESTful API library. It has been designed to make most of commonly used REST Endpoints available to the developers of thirt-party applications mainly LMSes such as Stud.IP, Moodle and ILIAS. Please refer to the Change Log for more info.

Note

As of version 1.2.0 the main class name has been changed from OpenCast to OpenCast. Please refer to Upgrade Log for more info.

Requisitions

PHP Version 7.2.5 or above as well as cURL are required. Additionaly, the requirements of guzzlehttp/guzzle must be fullfiled.

Installation

composer require elan-ev/opencast-api

Basic Usage

There are 2 approaches to use the Opencast REST Endpoints from this library:

The first one is via the generic OpencastApi\Opencast which contains all available Opencast endpoints (which are capable with the API version defined in the config). The advantage of using this approach is a better control over all available endpoints. (Recommended)

NOTE: When using this library against a distributed Opencast setup with admin and presentation split, you can pass another set of configuration as the second parameter when instantiating the OpencastApi\Opencast. Initially, the presentation node only takes care of search endpoint.

$config = [
      'url' => 'https://develop.opencast.org/',       // The API URL of the Opencast instance. (required)
      'username' => 'admin',                          // The API username. (required)
      'password' => 'opencast',                       // The API password. (required)
      'timeout' => 0,                                 // The API timeout. In seconds (default 0 to wait indefinitely). (optional)
      'connect_timeout' => 0,                         // The API connection timeout. In seconds (default 0 to wait indefinitely) (optional)
      'version' => null,                              // The API Version. (Default null). (optional)
];

$engageConfig = [
      'url' => 'https://develop.opencast.org/',       // The API URL of the Opencast instance. (required)
      'username' => 'admin',                          // The API username. (required)
      'password' => 'opencast',                       // The API password. (required)
      'timeout' => 0,                                 // The API timeout. In seconds (default 0 to wait indefinitely). (optional)
      'connect_timeout' => 0,                         // The API connection timeout. In seconds (default 0 to wait indefinitely) (optional)
      'version' => null,                              // The API version. (Default null). (optional)
];

use OpencastApi\Opencast;

// In case of a distributed Opencast setup
$opencastDualApi = new Opencast($config, $engageConfig);
// Or simply 
$opencastApi = new Opencast($config);

// Accessing Event Endpoints to get all events
$events = [];
$eventsResponse = $opencastApi->eventsApi->getAll();
if ($eventsResponse['code'] == 200) {
      $events = $eventsResponse['body'];
}

// Accessing Series Endpoints to get all series
$series = [];
$seriesResponse = $opencastApi->seriesApi->getAll();
if ($seriesResponse['code'] == 200) {
      $series = $seriesResponse['body'];
}

// ...

The second approach is to instantiate each REST endpoint class, which are located under OpencastApi\Rest\ namespace, when needed, but the down side of this is that it needs a OpencastApi\Rest\OcRestClient instance as its parameter. The advantage of this approach might be the methods' definitions in the IDE.

$config = [
      'url' => 'https://develop.opencast.org/',       // The API URL of the Opencast instance. (required)
      'username' => 'admin',                          // The API username. (required)
      'password' => 'opencast',                       // The API password. (required)
      'timeout' => 0,                                 // The API timeout. In seconds (default 0 to wait indefinitely). (optional)
      'connect_timeout' => 0,                         // The API connection timeout. In seconds (default 0 to wait indefinitely) (optional)
      'version' => null,                              // The API version. (Default null). (optional)
];


use OpencastApi\Rest\OcRestClient;
use OpencastApi\Rest\OcEventsApi;
use OpencastApi\Rest\OcSeriesApi;

// Get a client object.
$opencastClient = new OcRestClient($config);

// To get events.
$opencastEventsApi = new OcEventsApi($opencastClient);
$events = [];
$eventsResponse = $opencastEventsApi->getAll();
if ($eventsResponse['code'] == 200) {
      $events = $eventsResponse['body'];
}

// To get series.
$opencastSeriesApi = new OcSeriesApi($opencastClient);
$series = [];
$seriesResponse = $opencastSeriesApi->getAll();
if ($seriesResponse['body'] == 200) {
      $series = $seriesResponse['body'];
}

// ...

Configuration

The configuration is type of Array and has to be defined as follows:

$config = [
      'url' => 'https://develop.opencast.org/',       // The API URL of the Opencast instance. (required)
      'username' => 'admin',                          // The API username. (required)
      'password' => 'opencast',                       // The API password. (required)
      'timeout' => 0,                                 // The API timeout. In seconds (default 0 to wait indefinitely). (optional)
      'connect_timeout' => 0,                         // The API connection timeout. In seconds (default 0 to wait indefinitely) (optional)
      'version' => null,                              // The API version. (Default null). (optional)
];

NOTE: the configuration for presentation (engage node) responsible for search has to follow the same definition as normal config. But in case any parameter is missing, the value will be taken from the main config param.

Response

The return result of each call is an Array containing the following information:

[
      'code' => 200,                // The status code of the response
      'body' => '',                 // The result of the response. It can be type of string, array or object ('' || [] || {})
      'reason' => 'OK',             // The reason/message of response
      'location' => '',             // The location header of the response when available
]

Filters and Sorts

Filters and Sorts must be defined as associative Array, as follows:

// for example:

$filters = [
      'title' => 'The title name',
      'creator' => 'opencast admin'
];

$sorts = [
      'title' => 'DESC',
      'startDate' => 'ASC'
];

NOTE: Sometimes a filter can occur multiple times for example in Series API /get, filters like subject and identifier can occur multiple times. Therefore, an Array should be passed as filter value like following:

// for example:

$filters = [
      'identifier' => [
            '{first ID}',  '{second ID}'
      ],
      'subject' => [
            '{first Subject}',  '{second Subject}'
      ]
];

`runWithRoles([])`

Sometimes it is needed to perform the request with a disposable header of X-RUN-WITH-ROLES containing some roles (e.g. user ids) in order for Opencast to assume that those users has special access right.
It is commonly used to get data with onlyWithWriteAccess parameter for example to perform getAll in OcSeriesApi and grab those series that only specified users have access to!
In order to perform such requests it is needed to call the runWithRoles method before calling the desired function in a class:
NOTE: This method accepts an Array defining the roles to check against!

// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

// Role
$roles = ['ROLE_ADMIN'];
$seriesResponse = $opencastApi->seriesApi->runWithRoles($roles)->getAll(['onlyWithWriteAccess' => true]);

// Or direct class call
$opencastClient = \OpencastApi\Rest\OcRestClient($config);
$ocSeriesApi = \OpencastApi\Rest\OcSeriesApi($opencastClient);
// Role
$roles = ['ROLE_ADMIN'];
$seriesResponse = $ocSeriesApi->runWithRoles($roles)->getAll(['onlyWithWriteAccess' => true]);

NOTE: Roles can be either an Array including each role, or a comma separated string!

`noHeader()`

In order to perform a request call to an endpoint without any request headers/options, you can use this method before calling the desired function in an endpoint class: NOTE: This method accepts nothing (void).

// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

$baseResponse = $opencastApi->baseApi->noHeader()->get();

// Or direct class call
$opencastClient = \OpencastApi\Rest\OcRestClient($config);
$ocBaseApi = \OpencastApi\Rest\OcBaseApi($opencastClient);
$baseResponse = $ocBaseApi->noHeader()->get();

`setRequestTimeout($timeout = 0)`

In order to perform a request call with a different timeout value other than the one set in the configuration, you can use this method before calling the desired function in an endpoint class: NOTE: This method accepts integer defining a single use timeout in second.

// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

$baseResponse = $opencastApi->baseApi->setRequestTimeout(10)->get();

// Or direct class call
$opencastClient = \OpencastApi\Rest\OcRestClient($config);
$ocBaseApi = \OpencastApi\Rest\OcBaseApi($opencastClient);
$baseResponse = $ocBaseApi->setRequestTimeout(10)->get();

`setRequestConnectionTimeout($connectionTimeout = 0)`

In order to perform a request call with a different connection timeout value other than the one set in the configuration, you can use this method before calling the desired function in an endpoint class: NOTE: This method accepts integer defining a single use connection timeout in second.

// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

$baseResponse = $opencastApi->baseApi->setRequestConnectionTimeout(10)->get();

// Or direct class call
$opencastClient = \OpencastApi\Rest\OcRestClient($config);
$ocBaseApi = \OpencastApi\Rest\OcBaseApi($opencastClient);
$baseResponse = $ocBaseApi->setRequestConnectionTimeout(10)->get();

Available Opencast REST Service Endpoint

/api/*: all known API endpoints of Opencast are available to be used in this library. API Endpoints definitions WiKi
/ingest/*: all known Ingest endpoints are available. Ingest Endpoint definitions WiKi
/services/services.json: only services.json is available. Services Endpoint definitions WiKi
/search/{episode | lucene | series}.{json | xml}: only episode, lucene and series in JSON or XML format are available. Search Endpoint definitions WiKi
/capture-admin/*: all known Capture Admin endpoints are available. Capture Admin Endpoint definitions WiKi
/admin-ng/event/delete: only delete endpoint is available. Admin Ng Endpoint definitions WiKi
/recordings/*: all known Recording endpoints are available. Recordings Endpoint definitions WiKi
/series/*: all known Series endpoints are available. Series Endpoint definitions WiKi
/workflow/*: all known Workflow endpoints are available. Workflow Endpoint definitions WiKi
/sysinfo/bundles/version: (v1.1.1) only bundle version endpoint is available. Sysinfo Endpoint definitions WiKi

Naming convention

Classes:

Apart from 'Opencast' class, all other classes under OpencastApi\Rest\ namespace start with Oc followed by the name and the endpoint category. For example:

OcEventsApi contains 3 parts including Oc + Endpoint Name (Events) + Endpoint Category (Api)
OcServices contains 2 parts including Oc + Endpoint Name/Category (Services)

Opencast class properties:

The naming convention to access the endpoint subclasses from OpencastApi\Opencast as its properties, includes the name of the class without Oc in camelCase format. For example:

use OpencastApi\Opencast;
$config = [/*the config*/];
$opencast = new Opencast($config);

// Accessing OcEventsApi would be like: (without Oc and in camelCase format)
$ocEventsApi = $opencast->eventsApi;

elan-ev / opencast-api

Maintainers

Details