General
GET /api/series
Returns a list of series.
The following query string parameters are supported to filter, sort and paginate the returned list:
Query String Parameter | Type | Description |
---|---|---|
filter |
string |
A comma-separated list of filters to limit the results with (see Filtering). See the below table for the list of available filters |
sort |
string |
A comma-separated list of sort criteria (see Sorting). See the below table for the list of available sort criteria |
limit |
integer |
The maximum number of results to return (see Pagination) |
offset |
integer |
The index of the first result to return (see Pagination) |
The following filters are available:
Filter Name | Description |
---|---|
contributors |
Series where the contributors specified in the metadata field match. Can occur multiple times |
Creator |
Series where the creator specified in the metadata field match (please use creator for version 1.1.0 and higher instead) |
creationDate |
Series that were created between two dates. The two dates are in UTC format to the second i.e. yyyy-MM-ddTHH:mm:ssZ e.g. 2014-09-27T16:25Z. They are seperated by a forward slash (url encoded or not) so an example of the full filter would be CreationDate:2015-05-08T00:00:00.000Z/2015-05-10T00:00:00.000Z |
language |
Series based upon the language specified |
license |
Series based upon the license specified |
organizers |
Series where the organizers specified in the metadata field match. Can occur multiple times |
managedAcl |
Series who have the same managed acl name |
subject |
By the subject they are a part of. Can occur multiple times |
textFilter |
Filters series where any part of the series' metadata fields match this value |
title |
By the title of the series |
identifier |
By the technical identifiers of the series. Can occur multiple times (version 1.1.0 and higher) |
description |
By the description of the series (version 1.1.0 and higher) |
creator |
Series where the creator specified in the metadata field match (version 1.1.0 and higher) |
publishers |
Series where the publishers specified in the metadata field match. Can occur multiple times (version 1.1.0 and higher) |
rightsholder |
By the rights holder of the series (version 1.1.0 and higher) |
The list can be sorted by the following criteria:
Sort Criteria | Description |
---|---|
contributors |
By the series contributors |
created |
By when the series was created |
creator |
By who created the series |
title |
By the title of the series |
This request additionally supports the following query string parameters to include additional information directly in the response:
Query String Parameter | Type | Description |
---|---|---|
withacl |
boolean |
Whether the acl should be included in the response (version 1.5.0 and higher) |
Sample request
https://opencast.domain.com/api/series?filter=creator:Default Administrator&sort=title:ASC&limit=2&offset=1
Response
200 (OK)
: A (potentially empty) list of series is returned as JSON array contained JSON objects describing the series:
Field | Type | Description |
---|---|---|
identifier |
string |
The unique identifier of the series |
created * |
datetime |
The data when the series was created |
creator |
string |
The name of the user that has created the series |
title * |
string |
The title of the series |
contributors * |
array[string] |
The contributors of the series |
publishers * |
array[string] |
The publishers of the series |
subjects * |
array[string] |
The subjects of the series |
organizers * |
array[string] |
The organizers of the series |
description * |
string |
The description of the series (version 1.1.0 and higher) |
language * |
string |
The language of the series (version 1.1.0 and higher) |
license * |
string |
The license of the series (version 1.1.0 and higher) |
rightsholder * |
string |
The rights holder of the series (version 1.1.0 and higher) |
* Metadata fields from the default metadata catalog dublincore/series
Example
[
{
"identifier": "dc11ab0a-fd5b-462d-a939-0a4703df38cf",
"creator": "Opencast Project Administrator",
"created": "2018-03-19T15:40:21Z",
"subjects": [
"Mathematics"
],
"organizers": [
"John Doe",
"Prof. X"
],
"publishers": [
"University of Prof. X"
],
"contributors": [
"Hans Muster",
"Maria Müller"
],
"title": "Advanced Mathematics"
},
{
"identifier": "6a4462ca-3783-432a-81c3-962ca756dc6f",
"creator": "Opencast Project Administrator",
"created": "2018-03-19T15:41:20Z",
"subjects": [
"Physics",
"Mathematics"
],
"organizers": [
"Dr. Who"
],
"publishers": [
"University of Prof. X",
"Doctor Who"
],
"contributors": [
"Dr. Who"
],
"title": "Basics of Physics"
}
]
GET /api/series/{series_id}
Returns a single series.
Query String Parameter | Type | Description |
---|---|---|
withacl |
boolean |
Whether the acl should be included in the response (version 1.5.0 and higher) |
Response
200 (OK)
: The series is returned as a JSON object containing the following fields:
Field | Type | Description |
---|---|---|
identifier |
string |
The unique identifier of the series |
created * |
datetime |
The data when the series was created |
creator |
string |
The name of the user that has created the series |
title * |
string |
The title of the series |
contributors * |
array[string] |
The contributors of the series |
publishers * |
array[string] |
The publishers of the series |
subjects * |
array[string] |
The subjects of the series |
organizers * |
array[string] |
The organizers of the series |
organization * |
string |
The identifier of the tenant this series belongs to |
opt_out |
string |
Field is not used |
language * |
string |
The language of the series (version 1.1.0 and higher) |
license * |
string |
The license of the series (version 1.1.0 and higher) |
rightsholder * |
string |
The rights holder of the series (version 1.1.0 and higher) |
* Fields from the default metadata catalog dublincore/series
404 (NOT FOUND)
: The specified series does not exist.
Example
{
"identifier": "dc11ab0a-fd5b-462d-a939-0a4703df38cf",
"creator": "Opencast Project Administrator",
"opt_out": false,
"created": "2018-03-19T15:40:21Z",
"subjects": [
"Mathematics"
],
"organization": "mh_default_org",
"organizers": [
"John Doe",
"Prof. X"
],
"description": "This is a advanced mathematics course",
"publishers": [
"University of Prof. X"
],
"contributors": [
"Hans Muster",
"Maria Müller"
],
"title": "Advanced Mathematics"
}
GET /api/series/series.json
Returns the series matching the query parameters
The following query string parameters are supported to filter, sort and paginate the returned list:
Query String Parameter | Type | Description |
---|---|---|
q |
string |
Free text search |
edit |
boolean |
Whether this query should return only series that are editable |
fuzzyMatch |
boolean |
Whether a partial match on series id is allowed |
seriesId |
string |
The series identifier |
seriesTitle |
string |
The series title |
creator |
string |
The series creator |
contributor |
string |
The series contributor |
publisher |
string |
The series publisher |
rightsholder |
string |
The series rights holder |
createdfrom |
string |
Filter results by created from (yyyy-MM-dd'T'HH:mm:ss'Z') |
createdto |
string |
Filter results by created to (yyyy-MM-dd'T'HH:mm:ss'Z') |
language |
string |
The series language |
license |
string |
The series license |
subject |
string |
The series subject |
abstract |
string |
The series abstract |
sort |
string |
The sort order. May include any of the following: TITLE, SUBJECT, CREATOR, PUBLISHERS, CONTRIBUTORS, DESCRIPTION, CREATED_DATE_TIME, LANGUAGE, RIGHTS_HOLDER, MANAGED_ACL, LICENCE. Add '_DESC' to reverse the sort order (e.g. TITLE_DESC). |
offset |
string |
The offset |
count |
string |
Maximum number of results |
Sample request
https://opencast.domain.com/api/series/series.json?creator:Administrator&sort=title_DESC&limit=2
Response
200 (OK)
: A (potentially empty) list of series is returned as JSON array contained JSON objects describing the series:
Field | Type | Description |
---|---|---|
identifier |
string |
The unique identifier of the series |
license * |
string |
The license of the series (version 1.1.0 and higher) |
created * |
datetime |
The data when the series was created |
creator |
string |
The name of the user that has created the series |
title * |
string |
The title of the series |
contributors * |
array[string] |
The contributors of the series |
publishers * |
array[string] |
The publishers of the series |
subjects * |
array[string] |
The subjects of the series |
organizers * |
array[string] |
The organizers of the series |
description * |
string |
The description of the series (version 1.1.0 and higher) |
language * |
string |
The language of the series (version 1.1.0 and higher) |
rightsholder * |
string |
The rights holder of the series (version 1.1.0 and higher) |
POST /api/series
Creates a series.
Form Parameters | Required | Type | Description |
---|---|---|---|
metadata |
yes | catalogs |
Series metadata |
acl |
no | acl |
A collection of roles with their possible action |
theme |
no | string |
The theme ID to be applied to the series |
Sample
metadata:
[
{
"label": "Opencast Series DublinCore",
"flavor": "dublincore/series",
"fields": [
{
"id": "title",
"value": "Captivating title"
},
{
"id": "subjects",
"value": ["John Clark", "Thiago Melo Costa"]
},
{
"id": "description",
"value": "A great description"
}
]
}
]
acl:
[
{
"allow": true,
"action": "write",
"role": "ROLE_ADMIN"
},
{
"allow": true,
"action": "read",
"role": "ROLE_USER"
}
]
theme:
"1234"
Response
201 (CREATED)
: A new series is created and its identifier is returned in the Location
header.
400 (BAD REQUEST)
: The request is invalid or inconsistent.
401 (UNAUTHORIZED)
: The user doesn't have the rights to create the series.
Location: http://api.opencast.org/api/series/4fd0ef66-aea5-4b7a-a62a-a4ada0eafd6f
{
"identifier": "4fd0ef66-aea5-4b7a-a62a-a4ada0eafd6f"
}
DELETE /api/series/{series_id}
Deletes a series
Response
204 (NO CONTENT)
: The series has been deleted.
404 (NOT FOUND)
: The specified series does not exist.
Metadata
This section describes how to use the External API to work with metadata catalogs associated to series.
Opencast manages the bibliographic metadata of series using metadata catalogs which are identified by flavors.
The default metadata catalog for Opencast series has the flavor dublincore/series
. Opencast additionally supports
extended metadata catalogs for series that can be configured.
The External API supports both the default series metadata catalog and series extended metadata catalogs. For the default series metadata catalog, the metadata is directly returned in the responses.
Since the metadata catalogs can be configured, the External API provides a facility to retrieve the catalog configuration of series metadata catalogs. For more details about this mechanism, please refer to "Metadata Catalogs".
GET /api/series/{series_id}/metadata
Returns a series' metadata of all types.
Response
200 (OK)
: The series' metadata are returned as catalogs
404 (NOT FOUND)
: The specified series does not exist.
Example
[
{
"label": "EVENTS.EVENTS.DETAILS.CATALOG.EPISODE",
"flavor": "dublincore/series",
"fields": [
{
"id": "title",
"readOnly": false,
"value": "Captivating title",
"label": "EVENTS.EVENTS.DETAILS.METADATA.TITLE",
"type": "text",
"required": true
},
{
"id": "description",
"readOnly": false,
"value": "A great description",
"label": "EVENTS.EVENTS.DETAILS.METADATA.DESCRIPTION",
"type": "text_long",
"required": false
}
]
},
{
"label": "EVENTS.EVENTS.DETAILS.CATALOG.LICENSE",
"flavor": "license/series",
"fields": [
{
"id": "license",
"readOnly": false,
"value": "CCND",
"label": "EVENTS.EVENTS.DETAILS.METADATA.LICENSE",
"collection": {
"BSD": "EVENTS.LICENSE.BSD",
"GPL3": "EVENTS.LICENSE.GPL",
"CCND": "EVENTS.LICENSE.CCND"
},
"type": "text",
"required": false
}
]
}
]
GET /api/series/{series_id}/metadata
Returns a series' metadata collection of the given type when the query string parameter type is specified. For each metadata catalog there is a unique property called the flavor such as dublincore/series so the type in this example would be "dublincore/series".
Query String Parameters | Type | Description |
---|---|---|
type |
flavor |
The type of metadata to return |
Response
200 (OK)
: The series' metadata are returned as fields
above.
404 (NOT FOUND)
: The specified series does not exist.
Example
[
{
"id": "title",
"readOnly": false,
"value": "Captivating title",
"label": "EVENTS.EVENTS.DETAILS.METADATA.TITLE",
"type": "text",
"required": true
},
{
"id": "description",
"readOnly": false,
"value": "A great description",
"label": "EVENTS.EVENTS.DETAILS.METADATA.DESCRIPTION",
"type": "text_long",
"required": false
}
]
PUT /api/series/{series_id}/metadata
Update a series' metadata of the given type.
Query String Parameters | Required | Type | Description |
---|---|---|---|
type |
yes | flavor |
The type of metadata to update |
Form Parameters | Required | Type | Description |
---|---|---|---|
metadata |
yes | values |
Series metadata as Form param |
Note that metadata fields not contained in the argument won't be updated.
Example
metadata:
[
{
"id": "title",
"value": "Captivating title - edited"
},
{
"id": "creator",
"value": ["John Clark", "Thiago Melo Costa"]
},
{
"id": "description",
"value": "A great description - edited"
}
]
Response
200 (OK)
: The series' metadata have been updated.
400 (BAD REQUEST)
: The request is invalid or inconsistent.
404 (NOT FOUND)
: The specified series does not exist.
Returns: The full metadata catalog of the series
DELETE /api/series/{series_id}/metadata
Deletes a series' metadata catalog of the given type. All fields and values of that catalog will be deleted.
Query String Parameters | Required | Type | Description |
---|---|---|---|
type |
yes | flavor |
The type of metadata to delete |
Note that the default metadata catalog (type dublincore/series) cannot be deleted.
Response
204 (NO CONTENT)
: The metadata have been deleted.
403 (FORBIDDEN)
: The main metadata catalog dublincore/series cannot be deleted as it has mandatory fields.
404 (NOT FOUND)
: The specified series does not exist.
Access Policy
GET /api/series/{series_id}/acl
Returns a series' access policy.
Response
200 (OK)
: The series' access policy of type acl
is returned.
404 (NOT FOUND)
: The specified series does not exist.
Example
[
{
"allow": true,
"action": "write",
"role": "ROLE_ADMIN"
},
{
"allow": true,
"action": "read",
"role": "ROLE_USER"
}
]
PUT /api/series/{series_id}/acl
Updates a series' access policy.
Parameters | Required | Type | Description | Default | Version |
---|---|---|---|---|---|
acl |
yes | acl |
Access policy to be applied | ||
override |
no | boolean |
Whether the episode ACL of all events of this series should be removed | false | 1.2.0 |
Note that the existing access policy of the series will be overwritten.
Response
200 (OK)
: The updated access control list of type acl
is returned.
404 (NOT FOUND)
: The specified series does not exist.
Example
acl:
[
{
"allow": true,
"action": "write",
"role": "ROLE_ADMIN"
},
{
"allow": true,
"action": "read",
"role": "ROLE_USER"
}
]
returns
[
{
"allow": true,
"action": "write",
"role": "ROLE_ADMIN"
},
{
"allow": true,
"action": "read",
"role": "ROLE_USER"
}
]
Properties
Properties can be assigned to series in means of key-value pairs. Both the property name (key) and property value are
of type string
.
GET /api/series/{series_id}/properties
Returns a series' properties.
Response
200 (OK)
: The series' properties are returned as property
404 (NOT FOUND)
: The specified series does not exist.
Example
{
"ondemand": "true",
"live": "false"
}
PUT /api/series/{series_id}/properties
Add or update properties of a series.
Form parameters | Required | Type | Description |
---|---|---|---|
properties |
yes | property |
List of properties to be assigned to the series |
The request can be used to add new properties and/or update existing properties. Properties not included in the request are not affected.
Response
200 (OK)
: The added/updated series' properties are returned as JSON object.
404 (NOT FOUND)
: The specified series does not exist.
Example
Assume that the series already has the properties theme
=1000
and live
=true
.
To add the property ondemand
and update the value of the existing property live
the following form parameter is
used:
properties:
{
"ondemand": "true",
"live": "false"
}
The response of the request will contain the properties added/updated by this request:
{
"ondemand": "true",
"live": "false"
}
After this, the properties of the series are:
{
"theme": "1000",
"ondemand": "true",
"live": "false"
}