External API Events Service REST Documentation

GET /{eventId}
GET /{eventId}/acl
GET /{eventId}/media
GET /{eventId}/metadata
GET /{eventId}/publications/{publicationId}
GET /{eventId}/publications
GET /
GET /{eventId}/scheduling
POST /{eventId}/acl/{action}
POST /
DELETE /{eventId}
DELETE /{eventId}/acl/{action}/{role}
DELETE /{eventId}/metadata
PUT /{eventId}/acl
POST /{eventId}
PUT /{eventId}/metadata
PUT /{eventId}/scheduling
POST /{eventId}/track

Read methods

Method / Path: GET /{eventId}

Description: Returns a single event. By setting the optional sign parameter to true, the method will pre-sign distribution urls if signing is turned on in Opencast. Remember to consider the maximum validity of signed URLs when caching this response.

Path params: eventId: The event id

Response formats: application/json
application/v1.0.0+json
application/v1.1.0+json
application/v1.2.0+json
application/v1.3.0+json
application/v1.4.0+json
application/v1.5.0+json
application/v1.6.0+json
application/v1.7.0+json
application/v1.8.0+json
application/v1.9.0+json
application/v1.10.0+json
application/v1.11.0+json

Status codes: 200: OK, The event is returned.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}?sign={sign}&withacl={withacl}&withmetadata={withmetadata}&withscheduling={withscheduling}&withpublications={withpublications}&includeInternalPublication={includeInternalPublication}

Testing form (click to reveal)

Method / Path: GET /{eventId}/acl

Description: Returns an event's access policy.

Path params: eventId: The event id

Optional (query) params: NONE

Status codes: 200: OK, The access control list for the specified event is returned.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/acl

Testing form (click to reveal)

Method / Path: GET /{eventId}/media

Description: Returns media tracks of specific single event.

Path params: eventId: The event id

Optional (query) params: NONE

Status codes: 200: OK, The event's media is returned.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/media

Testing form (click to reveal)

Method / Path: GET /{eventId}/metadata

Description: Returns the event's metadata of the specified type. For a metadata catalog there is the flavor such as 'dublincore/episode' and this is the unique type.

Path params: eventId: The event id

Optional (query) params: type: The type of metadata to get

Status codes: 200: OK, The metadata collection is returned.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/metadata?type={type}

Testing form (click to reveal)

Method / Path: GET /{eventId}/publications/{publicationId}

Description: Returns a single publication.

Path params: eventId: The event id
publicationId: The publication id

Optional (query) params: sign: Whether public distribution urls should be signed.

Status codes: 200: OK, The track details are returned.
404: Not Found, The specified event or publication does not exist.

Testing:

Sample: /{eventId}/publications/{publicationId}?sign={sign}

Testing form (click to reveal)

Method / Path: GET /{eventId}/publications

Description: Returns an event's list of publications.

Path params: eventId: The event id

Optional (query) params: sign: Whether public distribution urls should be signed.
includeInternalPublication: Whether internal publications should be included.

Status codes: 200: OK, The list of publications is returned.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/publications?sign={sign}&includeInternalPublication={includeInternalPublication}

Testing form (click to reveal)

Method / Path: GET /

Description: Returns a list of events. By setting the optional sign parameter to true, the method will pre-sign distribution urls if signing is turned on in Opencast. Remember to consider the maximum validity of signed URLs when caching this response.

Path params: NONE

Optional (query) params: sign: Whether public distribution urls should be signed.
withacl: Whether the acl metadata should be included in the response.
withmetadata: Whether the metadata catalogs should be included in the response.
withscheduling: Whether the scheduling information should be included in the response.
withpublications: Whether the publication ids and urls should be included in the response.
includeInternalPublication: Whether internal publications should be included.
onlyWithWriteAccess: Whether only to get the events to which we have write access.
filter: Usage [Filter Name]:[Value to Filter With]. Multiple filters can be used by combining them with commas ",". Available Filters: presenters, contributors, location, textFilter, series, subject. If API ver > 1.1.0 also: identifier, title, description, series_name, language, created, license, rightsholder, is_part_of, source, status, agent_id, start, technical_start.
sort: Sort the results based upon a list of comma seperated sorting criteria. In the comma seperated list each type of sorting is specified as a pair such as: :ASC or :DESC. Adding the suffix ASC or DESC sets the order as ascending or descending order and is mandatory.
limit(Default value=0): The maximum number of results to return for a single request.
offset(Default value=0): The index of the first result to return.

Status codes: 200: OK, A (potentially empty) list of events is returned.

Testing:

Sample: /?sign={sign}&withacl={withacl}&withmetadata={withmetadata}&withscheduling={withscheduling}&withpublications={withpublications}&includeInternalPublication={includeInternalPublication}&onlyWithWriteAccess={onlyWithWriteAccess}&filter={filter}&sort={sort}&limit=0&offset=0

Testing form (click to reveal)

Form action: /api/events/

sign:		Whether public distribution urls should be signed.
withacl:		Whether the acl metadata should be included in the response.
withmetadata:		Whether the metadata catalogs should be included in the response.
withscheduling:		Whether the scheduling information should be included in the response.
withpublications:		Whether the publication ids and urls should be included in the response.
includeInternalPublication:		Whether internal publications should be included.
onlyWithWriteAccess:		Whether only to get the events to which we have write access.
filter:		Usage [Filter Name]:[Value to Filter With]. Multiple filters can be used by combining them with commas ",". Available Filters: presenters, contributors, location, textFilter, series, subject. If API ver > 1.1.0 also: identifier, title, description, series_name, language, created, license, rightsholder, is_part_of, source, status, agent_id, start, technical_start.
sort:		Sort the results based upon a list of comma seperated sorting criteria. In the comma seperated list each type of sorting is specified as a pair such as: :ASC or :DESC. Adding the suffix ASC or DESC sets the order as ascending or descending order and is mandatory.
limit:		The maximum number of results to return for a single request.
offset:		The index of the first result to return.

Response:

Method / Path: GET /{eventId}/scheduling

Description: Returns an event's scheduling information.

Path params: eventId: The event id

Optional (query) params: NONE

Response formats: application/json
application/v1.1.0+json
application/v1.2.0+json
application/v1.3.0+json
application/v1.4.0+json
application/v1.5.0+json
application/v1.6.0+json
application/v1.7.0+json
application/v1.8.0+json
application/v1.9.0+json
application/v1.10.0+json
application/v1.11.0+json

Status codes: 200: OK, The scheduling information for the specified event is returned.
204: No Content, The specified event has no scheduling information.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/scheduling

Testing form (click to reveal)

Write methods

Method / Path: POST /{eventId}/acl/{action}

Description: Grants permission to execute action on the specified event to any user with role role. Note that this is a convenience method to avoid having to build and post a complete access control list.

Path params: eventId: The event id
action: The action that is allowed to be executed

Required (form) params: role: The role that is granted permission

Optional (form) params: NONE

Status codes: 204: No Content, The permission has been created in the access control list of the specified event.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/acl/{action}

Testing form (click to reveal)

Method / Path: POST /

Description: Creates an event by sending metadata, access control list, processing instructions and files in a multipart request.

Path params: NONE

Optional (form) params: acl: A collection of roles with their possible action
metadata: Event metadata as Form param
scheduling: Scheduling information as Form param
presenter: Presenter movie track
presentation: Presentation movie track
audio: Audio track
processing: Processing instructions task configuration

Status codes: 201: Created, A new event is created and its identifier is returned in the Location header.
409: Conflict, The event could not be created due to a scheduling conflict.
400: Bad Request, The request is invalid or inconsistent..

Testing:

Sample: /

Testing form (click to reveal)

Method / Path: DELETE /{eventId}

Description: Deletes an event.

Path params: eventId: The event id

Optional (query) params: NONE

Status codes: 204: No Content, The event has been deleted.
202: Accepted, The retraction of publications has started.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}

Testing form (click to reveal)

Method / Path: DELETE /{eventId}/acl/{action}/{role}

Description: Revokes permission to execute action on the specified event from any user with role role.

Path params: eventId: The event id
action: The action that is no longer allowed to be executed
role: The role that is no longer granted permission

Optional (query) params: NONE

Status codes: 204: No Content, The permission has been revoked from the access control list of the specified event.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/acl/{action}/{role}

Testing form (click to reveal)

Method / Path: DELETE /{eventId}/metadata

Description: Delete the metadata namespace catalog of the specified event. This will remove all fields and values of the catalog.

Path params: eventId: The event id

Required (form) params: type: The type of metadata to delete

Optional (query) params: NONE

Status codes: 204: No Content, The metadata of the given namespace has been updated.
403: Forbidden, The main metadata catalog dublincore/episode cannot be deleted as it has mandatory fields.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/metadata

Testing form (click to reveal)

Method / Path: PUT /{eventId}/acl

Description: Update an event's access policy.

Path params: eventId: The event id

Required (form) params: acl: Access policy

Optional (form) params: NONE

Status codes: 204: No Content, The access control list for the specified event is updated.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/acl

Testing form (click to reveal)

Method / Path: POST /{eventId}

Description: Updates an event.

Path params: eventId: The event id

Status codes: 204: No Content, The event has been updated.
409: Conflict, The event could not be updated due to a scheduling conflict.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}

Testing form (click to reveal)

Method / Path: PUT /{eventId}/metadata

Description: Update the metadata with the matching type of the specified event. For a metadata catalog there is the flavor such as 'dublincore/episode' and this is the unique type.

Path params: eventId: The event id

Required (form) params: type: The type of metadata to update
metadata: Metadata catalog in JSON format

Optional (form) params: NONE

Status codes: 200: OK, The metadata of the given namespace has been updated.
400: Bad Request, The request is invalid or inconsistent.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/metadata

Testing form (click to reveal)

Method / Path: PUT /{eventId}/scheduling

Description: Update an event's scheduling information.

Path params: eventId: The event id

Required (form) params: scheduling: Scheduling Information

Optional (form) params: allowConflict: Allow conflicts when updating scheduling

Status codes: 204: No Content, The scheduling information for the specified event is updated.
406: Not Acceptable, The specified event has no scheduling information to update.
409: Conflict, The scheduling information could not be updated due to a conflict.
404: Not Found, The specified event does not exist.

Testing:

Sample: /{eventId}/scheduling

Testing form (click to reveal)

Method / Path: POST /{eventId}/track

Description: Update an events track for a given flavor

Path params: eventId: The event id

Required (form) params: flavor: Flavor to add track to, e.g. captions/source
overwriteExisting: If true, all other tracks in the specified flavor are REMOVED. If tags argument contains a lang:LANG-CODE tag, only elements with same tag would be removed.
track: The track file

Optional (form) params: tags: Comma separated list of tags for the given track, e.g. archive,publish. If a 'lang:LANG-CODE' tag exists and overwriteExisting=true only tracks with same lang tag and flavor will be replaced. This behavior is used for captions.

Status codes: 404: Not Found, The specified event does not exist.
200: OK, The track has been added to the event.
400: Bad Request, The request is invalid or inconsistent.

Testing:

Sample: /{eventId}/track

Testing form (click to reveal)

External API Events Service REST Documentation

Table of Contents

Read methods

Write methods