Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
ferishili committed Sep 16, 2022
1 parent ed820d6 commit ca37ebd
Showing 1 changed file with 22 additions and 22 deletions.
44 changes: 22 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ This PHP composer package is meant to provide a unified easy-to-use Opencast RES
# Basic Usage
There are 2 approaches to use the Opencast REST Endpoints from this library:

1. 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. <b>(Recommended)</b>
1. 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. <b>(Recommended)</b>

<b>NOTE:</b> 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.
<b>NOTE:</b> 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.
```php
$config = [
'url' => 'https://develop.opencast.org/', // The API URL of the Opencast instance. (required)
Expand All @@ -32,12 +32,12 @@ $engageConfig = [
'version' => null, // The API version. (Default null). (optional)
];

use OpencastApi\OpenCast;
use OpencastApi\Opencast;

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

// Accessing Event Endpoints to get all events
$events = [];
Expand Down Expand Up @@ -152,9 +152,9 @@ $filters = [
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.<br />It is commonly used to get data with `onlyWithWriteAccess` parameter for example to perform [`getAll`](https://github.com/elan-ev/opencast-php-library/wiki/OcSeriesApi#getallparams--) in `OcSeriesApi` and grab those series that only specified users have access to!<br />In order to perform such requests it is needed to call the `runWithRoles` method <b>before</b> calling the desired function in a class:<br />
NOTE: This method <b>accepts</b> an `Array` defining the roles to check against!
```php
// With OpenCast generic class
use OpencastApi\OpenCast;
$opencastApi = new OpenCast($config);
// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

// Role
$roles = ['ROLE_ADMIN'];
Expand All @@ -173,9 +173,9 @@ $seriesResponse = $ocSeriesApi->runWithRoles($roles)->getAll(['onlyWithWriteAcce
In order to perform a request call to an endpoint without any request headers/options, you can use this method <b>before</b> calling the desired function in an endpoint class:
NOTE: This method <b>accepts</b> nothing (`void`).<br />
```php
// With OpenCast generic class
use OpencastApi\OpenCast;
$opencastApi = new OpenCast($config);
// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

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

Expand All @@ -189,9 +189,9 @@ $baseResponse = $ocBaseApi->noHeader()->get();
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 <b>before</b> calling the desired function in an endpoint class:
NOTE: This method <b>accepts</b> integer defining a single use timeout in second.<br />
```php
// With OpenCast generic class
use OpencastApi\OpenCast;
$opencastApi = new OpenCast($config);
// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

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

Expand All @@ -205,9 +205,9 @@ $baseResponse = $ocBaseApi->setRequestTimeout(10)->get();
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 <b>before</b> calling the desired function in an endpoint class:
NOTE: This method <b>accepts</b> integer defining a single use connection timeout in second.<br />
```php
// With OpenCast generic class
use OpencastApi\OpenCast;
$opencastApi = new OpenCast($config);
// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

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

Expand Down Expand Up @@ -241,16 +241,16 @@ $baseResponse = $ocBaseApi->setRequestConnectionTimeout(10)->get();

# 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:
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:
## 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:
```php
use OpencastApi\OpenCast;
use OpencastApi\Opencast;
$config = [/*the config*/];
$opencast = new OpenCast($config);
$opencast = new Opencast($config);

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

0 comments on commit ca37ebd

Please sign in to comment.