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"
}