Skip to content

OcSeriesApi

Jump to bottom
FarbodZamani edited this page Apr 19, 2023 · 9 revisions

This class contains all REST API calls to the /api/series endpoint.

Namespace

It is accessible under OpencastApi\Rest namespace.

How to use

  1. In OpencastApi\OpenCast as its property with OpenCast properties naming convention:
use OpencastApi\OpenCast;
$opencastApi = new OpenCast($config);
$ocSeriesApi = $opencastApi->seriesApi;
...
  1. Direct instantiation:
use OpencastApi\Rest\OcRestClient;
use OpencastApi\Rest\OcSeriesApi;
$ocRestClient = new OcRestClient($config);
$ocSeriesApi = new OcSeriesApi($ocRestClient);
...

Functions

Consumable functions are listed below:

getAll($params = [])

Returns the list of series. More Detail

  • $params is an optional array that could contain the following:
[
    'onlyWithWriteAccess' => (boolean) {Whether only to get the series to which we have write access. },
    'withacl' => (boolean) {Whether the acl should be included in the response (version 1.5.0 and higher)},
    'sort' => (array) {an assiciative array for sorting e.g. ['title' => 'DESC']},
    'limit' => (int) {the maximum number of results to return},
    'offset' => (int) {the index of the first result to return},
    'filter' => (array) {an assiciative array for filtering e.g. ['title' => '{series title}']},
]
  • Returns an array: ['code' => 200, 'body' => '{A (potentially empty) list of series }']

getAllFullTextSearch($params = [])

Returns the series matching the query parameters as JSON (array). More Detail (From v1.3.0)

  • $params is an optional array that could contain the following:
[
    'q' => '{Free text search}',
    'edit' => '(boolean){Whether this query should return only series that are editable}',
    'fuzzyMatch' => '(boolean){Whether the seriesId can be used for a partial match. The default is an exact match}',
    'seriesId' => '{The series identifier}',
    'seriesTitle' => '{The series title}',
    'creator' => '{The series creator}',
    'contributor' => '{The series contributor}',
    'publisher' => '{The series publisher}',
    'rightsholder' => '{The series rights holder}',
    'createdfrom' => '{Filter results by created from (yyyy-MM-dd'T'HH:mm:ss'Z') }',
    'createdto' => '{Filter results by created to (yyyy-MM-dd'T'HH:mm:ss'Z')) }',
    'language' => '{The series language}',
    'license' => '{The series license}',
    'subject' => '{The series subject}',
    'abstract' => '{The series abstract}',
    'description' => '{The series description}',
    'sort' => '{The sort order. May include any of the following: TITLE, SUBJECT, CREATOR, PUBLISHER, CONTRIBUTOR, ABSTRACT, DESCRIPTION, CREATED, AVAILABLE_FROM, AVAILABLE_TO, LANGUAGE, RIGHTS_HOLDER, SPATIAL, TEMPORAL, IS_PART_OF, REPLACES, TYPE, ACCESS, LICENCE. Add '_DESC' to reverse the sort order (e.g. TITLE_DESC)}',
    'startPage' => '{The page offset}',
    'count' => '{Results per page (max 100)}',
]
  • Returns an array: ['code' => 200, 'body' => '{the series search results as JSON (array)}']

get($seriesId, $withacl = false)

Returns a single series. More Detail

  • $seriesId (string) the identifier of the series

  • $withacl (boolean) (optional) Whether the acl should be included in the response (version 1.5.0 and higher)

  • Returns an array: ['code' => 200, 'body' => '{The series (object)}']

create($metadata, $acls , $theme = '')

Creates a series. More Detail

  • $metadata (string|array) Series metadata

  • $acls (string|array) A collection of roles with their possible action

  • $theme (string) (optional) The theme ID to be applied to the series

  • Returns an array: ['code' => 201, 'reason' => 'Created', 'body' => '{The identifier of new series (object)}', 'location' => '{the url}']

delete($seriesId)

Deletes a series. More Detail

  • $seriesId (string) the series identifier

  • Returns an array: ['code' => 204, 'reason' => 'No Content'] (The series has been deleted.)

getMetadata($seriesId, $type = '')

Returns a series' metadata of all types or returns a series' metadata collection of the given type when the query string parameter type is specified. More Detail

  • $seriesId (string) the series identifier

  • $type (string) (optional) The type of metadata to return

  • Returns an array: ['code' => 200, 'body' => '{The series' metadata}']

updateAllMetadata($seriesId, $metadata)

Update all series metadata. More Detail

  • $seriesId (string) the series identifier

  • $metadata (string|array) Series metadata

  • Returns an array: ['code' => 200, 'reason' => 'OK'] (The series' metadata have been updated.)

updateMetadata($seriesId, $metadata, $type = 'dublincore/series')

Updates a series' metadata of the given type. More Detail

  • $seriesId (string) the series identifier

  • $metadata (string|array) Series metadata

  • $type (string) (optional) The type of metadata to get (Default: "dublincore/series")

  • Returns an array: ['code' => 200, 'reason' => 'OK'] (The series' metadata have been updated.)

deleteMetadata($seriesId, $type)

Deletes a series' metadata catalog of the given type. More Detail

  • $seriesId (string) the series identifier

  • $type (string) The type of metadata to delete

  • Returns an array: ['code' => 204, 'reason' => 'No Content'] (The metadata have been deleted)

getAcl($seriesId)

Returns a series' access policy. More Detail

  • $seriesId (string) the series identifier

  • Returns an array: ['code' => 200, 'body' => '{The series' access policy}']

updateAcl($seriesId, $acls, $override = false)

Updates a series' access policy. Note that the existing access policy of the series will be overwritten More Detail

  • $seriesId (string) the series identifier

  • $acls (string|array) Access policy to be applied

  • $override (boolean) (optional) Whether the episode Acl of all events of this series should be removed (Default value: false) (version 1.2.0 or heigher)

  • Returns an array: ['code' => 200, 'reason' => 'OK'] (The access control list for the specified series is updated)

emptyAcl($seriesId, $override = false)

Removes all Acls for the series. It is basically, an updateAcl call that overwrites acls with empty array. More Detail

  • $seriesId (string) the series identifier

  • $override (boolean) (optional) Whether the episode Acl of all events of this series should be removed (Default value: false) (version 1.2.0 or heigher)

  • Returns an array: ['code' => 200, 'reason' => 'OK'] (The access control list for the specified series is updated)

getProperties($seriesId)

Returns a series' properties. More Detail

  • $seriesId (string) the series identifier

  • Returns an array: ['code' => 200, 'body' => '{The series' properties}']

updateProperties($seriesId, $properties)

Add or update properties of a series. The request can be used to add new properties and/or update existing properties. Properties not included in the request are not affected. More Detail

  • $seriesId (string) the series identifier

  • $properties (string|array) List of properties to be assigned to the series

  • Returns an array: ['code' => 200, 'body' => '{The added/updated series' properties}']

addProperties($seriesId, $properties)

Add or update properties of a series. The request can be used to add new properties and/or update existing properties. Properties not included in the request are not affected. (it is the updateProperties function with another name to make it easier to maintain.) More Detail

  • $seriesId (string) the series identifier

  • $properties (string|array) List of properties to be assigned to the series

  • Returns an array: ['code' => 200, 'body' => '{The added/updated series' properties}']

Clone this wiki locally