External API Configuration
The External API is an integral part of Opencast and therefore does not need to be enabled. To be able to access the External API, you need to configure a user that is authorized to do so.
Perform the following steps to get the External API running:
- Enable basic authentication (see section Authentication)
- Create a new user or choose an existing user (administrative user interface)
- Authorize the user to access the External API (see section Authorization)
- Test whether access works (see section Testing)
Authentication
The External API currently only supports basic authentication. To enable basic authentication, uncomment the following
blocks in /etc/security/mh_default_org.xml
:
<!-- Basic authentication
<sec:custom-filter after="BASIC_AUTH_FILTER" ref="basicAuthenticationFilter" />
-->
<!-- Basic authentication
<bean id="basicEntryPoint" class="org.springframework.security.web.authentication.www.BasicAuthenticationEntryPoint">
<property name="realmName" value="Opencast"/>
</bean>
-->
<!-- Basic authentication
<bean id="basicAuthenticationFilter" class="org.springframework.security.web.authentication.www.BasicAuthenticationFilter">
<property name="authenticationManager" ref="authenticationManager"/>
<property name="authenticationEntryPoint" ref="basicEntryPoint"/>
</bean>
-->
Note: Since basic authentication involves sending unencrypted passwords over the network, it is strongly recommended to use HTTPS.
Authorization
The External API supports fine-grained access control on request level allowing it to be tailored to your specific needs. A number of roles are used to authorize access to individual endpoints. Those roles can be configured directly in the Opencast administrative user interface.
Note: Users owning the role ROLE_ADMIN have full access to the External API.
Base API
ROLE | METHOD | URL |
---|---|---|
ROLE_API | GET | /api /api/info/* /api/info/me/* /api/version /api/version/* |
Events API
ROLE | METHOD | URL |
---|---|---|
ROLE_API_EVENTS_CREATE | POST | /api/events |
ROLE_API_EVENTS_VIEW | GET | /api/events /api/events/* |
ROLE_API_EVENTS_EDIT | PUT POST |
/api/events/* /api/events/* |
ROLE_API_EVENTS_DELETE | DELETE | /api/events/* |
ROLE_API_EVENTS_ACL_VIEW | GET | /api/events/*/acl |
ROLE_API_EVENTS_ACL_EDIT | PUT POST |
/api/events/*/acl /api/events/*/acl/* |
ROLE_API_EVENTS_ACL_DELETE | DELETE | /api/events/*/acl/*/* |
ROLE_API_EVENTS_MEDIA_VIEW | GET | /api/events/*/media /api/events/*/media/* |
ROLE_API_EVENTS_METADATA_VIEW | GET | /api/events/*/metadata /api/events/*/metadata/* |
ROLE_API_EVENTS_METADATA_EDIT | PUT | /api/events/*/metadata /api/events/*/metadata/* |
ROLE_API_EVENTS_METADATA_DELETE | DELETE | /api/events/*/metadata /api/events/*/metadata/* |
ROLE_API_EVENTS_PUBLICATIONS_VIEW | GET | /api/events/*/publications /api/events/*/publications/* |
ROLE_API_EVENTS_SCHEDULING_EDIT | PUT | /api/events/*/scheduling |
ROLE_API_EVENTS_SCHEDULING_VIEW | GET | /api/events/*/scheduling |
Series API
ROLE | METHOD | URL |
---|---|---|
ROLE_API_SERIES_CREATE | POST | /api/series |
ROLE_API_SERIES_VIEW | GET | /api/series /api/series/* |
ROLE_API_SERIES_EDIT | PUT | /api/series/* |
ROLE_API_SERIES_ACL_VIEW | GET | /api/series/*/acl |
ROLE_API_SERIES_ACL_EDIT | PUT | /api/series/*/metadata /api/series/*/metadata/* |
ROLE_API_SERIES_METADATA_VIEW | GET | /api/series/*/metadata /api/series/*/metadata/* |
ROLE_API_SERIES_METADATA_EDIT | PUT | /api/series/*/metadata /api/series/*/metadata/* |
ROLE_API_SERIES_METADATA_DELETE | DELETE | /api/series/*/metadata /api/series/*/metadata/* |
ROLE_API_SERIES_PROPERTIES_VIEW | GET | /api/series/*/properties |
ROLE_API_SERIES_PROPERTIES_EDIT | PUT | /api/series/*/properties |
ROLE_API_SERIES_DELETE | DELETE | /api/series/* |
Statistics API
ROLE | METHOD | URL |
---|---|---|
ROLE_API_STATISTICS_VIEW | GET | /api/statistics/providers /api/statistics/providers/* |
ROLE_API_STATISTICS_VIEW | POST | /api/statistics/data/query |
Groups API
ROLE | METHOD | URL |
---|---|---|
ROLE_API_GROUPS_CREATE | POST | /api/groups |
ROLE_API_GROUPS_VIEW | GET | /api/groups /api/groups/* |
ROLE_API_GROUPS_EDIT | PUT POST |
/api/groups/* /api/groups/*/members/* |
ROLE_API_GROUPS_DELETE | DELETE | /api/groups/* |
Security API
ROLE | METHOD | URL |
---|---|---|
ROLE_API_SECURITY_EDIT | POST | /api/security/sign |
Agents API
ROLE | METHOD | URL |
---|---|---|
ROLE_API_CAPTURE_AGENTS_VIEW | GET | /api/agents/api/agents/* |
Workflow API
ROLE | METHOD | URL |
---|---|---|
ROLE_API_WORKFLOW_INSTANCE_CREATE | POST | /api/workflow |
ROLE_API_WORKFLOW_INSTANCE_VIEW | GET | /api/workflow /api/workflow/* |
ROLE_API_WORKFLOW_INSTANCE_EDIT | PUT | /api/workflow/* |
ROLE_API_WORKFLOW_INSTANCE_DELETE | DELETE | /api/workflow/* |
ROLE_API_WORKFLOW_DEFINITION_VIEW | GET | /api/workflow-definitions /api/workflow-definitions/* |
Listprovider API
ROLE | METHOD | URL |
---|---|---|
ROLE_API_LISTPROVIDERS_VIEW | GET | /api/listproviders |
Playlists API
ROLE | METHOD | URL |
---|---|---|
ROLE_API_PLAYLISTS_CREATE | POST | /api/playlists |
ROLE_API_PLAYLISTS_VIEW | GET | /api/playlists |
ROLE_API_PLAYLISTS_EDIT | POST | /api/playlists |
ROLE_API_PLAYLISTS_DELETE | DELETE | /api/playlists |
User- and Role-switching
The External API supports user- and role-switching, i.e. it is possible to perform requests on behalf of another user or role. The be able to perform this kind of requests, the user doing the actual requests needs to own ROLE_SUDO.
For more details on this API, please take a look at the developer documentation under External API.
Testing
curl -u <api-user>:<api-user-passowrd> <admin-node>/api/info/me
should return a JSON containing information about the user api-user.
Accessing Distribution Artefacts
A major use case of the External API is to provide External Applications secure access to distribution artefacts.
For this purpose, Opencast comes with a special workflow operation: WOH publish-configure (see ConfigurablePublishWorkflowOperationHandler) creates publication elements that do not just contain a single URL to the publication channel, but also contain URLs for each of the attachments and tracks that have been published.
Note: Secure access to distribution artefacts requires stream security to be enabled, see Stream Security Configuration.