General Notes
- All paths above are relative to the REST endpoint base (something like http://your.server/files)
- If the service is down or not working it will return a status 503, this means the the underlying service is not working and is either restarting or has failed
- A status code 500 means a general failure has occurred which is not recoverable and was not anticipated. In other words, there is a bug! You should file an error report with your server logs from the time when the error occurred: Opencast Issue Tracker
Table of Contents
- GET /configurationPanel
- GET /count
- GET /mediaPackage/{id}/currentInstance.json
- GET /definition/{id}.json
- GET /definition/{id}.xml
- GET /definitions.json
- GET /definitions.xml
- GET /handlers.json
- GET /mediaPackage/{id}/hasActiveWorkflows
- GET /statemappings.json
- GET /user/{id}/hasActiveWorkflows
- GET /instance/{id}.json
- GET /instance/{id}.xml
- GET /mediaPackage/{id}/instances.json
- DELETE /remove/{id}
- POST /replaceAndresume
- POST /resume
- POST /start
- POST /stop
- POST /suspend
- POST /update
Read methods
Method / Path: | GET /configurationPanel |
---|---|
Description: | Get the configuration panel for a specific workflow |
Path params: | NONE |
Optional (query) params: | definitionId: The workflow definition identifier |
Response formats: | text/html |
Status codes: | 200: OK, The workflow configuration panel. |
Notes: |
|
Testing: |
Sample:
/configurationPanel?definitionId={definitionId}
Testing form (click to reveal)
|
Method / Path: | GET /count |
---|---|
Description: | Returns the number of workflow instances in a specific state |
Path params: | NONE |
Optional (query) params: | state: The workflow state |
Response formats: | text/plain |
Status codes: | 200: OK, The number of workflow instances. |
Notes: |
|
Testing: |
Sample:
/count?state={state}
Testing form (click to reveal)
|
Method / Path: | GET /mediaPackage/{id}/currentInstance.json |
---|---|
Description: | Returns the current workflow for a media package |
Path params: | id: The media package identifier |
Optional (query) params: | NONE |
Response formats: | application/json |
Status codes: |
200: OK, Returns the workflows for a media package. 404: Not Found, Current workflow not found. |
Notes: |
|
Testing: |
Sample:
/mediaPackage/{id}/currentInstance.json
Testing form (click to reveal)
|
Method / Path: | GET /definition/{id}.json |
---|---|
Description: | Returns a single workflow definition |
Path params: | id: The workflow definition identifier |
Optional (query) params: | NONE |
Response formats: | application/json |
Status codes: |
200: OK, The workflow definition. 404: Not Found, Workflow definition not found. |
Notes: |
|
Testing: |
Sample:
/definition/{id}.json
Testing form (click to reveal)
|
Method / Path: | GET /definition/{id}.xml |
---|---|
Description: | Returns a single workflow definition |
Path params: | id: The workflow definition identifier |
Optional (query) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, The workflow definition. 404: Not Found, Workflow definition not found. |
Notes: |
|
Testing: |
Sample:
/definition/{id}.xml
Testing form (click to reveal)
|
Method / Path: | GET /definitions.json |
---|---|
Description: | List all available workflow definitions as JSON |
Path params: | NONE |
Optional (query) params: | NONE |
Response formats: | application/json |
Status codes: | 200: OK, The workflow definitions. |
Returned Entity Schema: | |
Notes: |
|
Testing: |
Sample:
/definitions.json
/workflow/definitions.json
|
Method / Path: | GET /definitions.xml |
---|---|
Description: | List all available workflow definitions as XML |
Path params: | NONE |
Optional (query) params: | NONE |
Response formats: | application/xml |
Status codes: | 200: OK, The workflow definitions. |
Returned Entity Schema: | |
Notes: |
|
Testing: |
Sample:
/definitions.xml
/workflow/definitions.xml
|
Method / Path: | GET /handlers.json |
---|---|
Description: | List all registered workflow operation handlers (implementations). |
Path params: | NONE |
Optional (query) params: | NONE |
Status codes: | 200: OK, A JSON representation of the registered workflow operation handlers |
Notes: |
|
Testing: |
Sample:
/handlers.json
/workflow/handlers.json
|
Method / Path: | GET /mediaPackage/{id}/hasActiveWorkflows |
---|---|
Description: | Returns if a media package has active workflows |
Path params: | id: The media package identifier |
Optional (query) params: | NONE |
Response formats: | application/json |
Status codes: | 200: OK, Whether the media package has active workflows. |
Notes: |
|
Testing: |
Sample:
/mediaPackage/{id}/hasActiveWorkflows
Testing form (click to reveal)
|
Method / Path: | GET /statemappings.json |
---|---|
Description: | Get all workflow state mappings |
Path params: | NONE |
Optional (query) params: | NONE |
Status codes: | 200: OK, A JSON representation of the workflow state mappings |
Notes: |
|
Testing: |
Sample:
/statemappings.json
/workflow/statemappings.json
|
Method / Path: | GET /user/{id}/hasActiveWorkflows |
---|---|
Description: | Returns if there are currently workflow(s) running thatwere started by the given user |
Path params: | id: The user identifier |
Optional (query) params: | NONE |
Response formats: | application/json |
Status codes: | 200: OK, Whether there are active workflow for the user. |
Notes: |
|
Testing: |
Sample:
/user/{id}/hasActiveWorkflows
Testing form (click to reveal)
|
Method / Path: | GET /instance/{id}.json |
---|---|
Description: | Get a specific workflow instance. |
Path params: | id: The workflow instance identifier |
Optional (query) params: | NONE |
Response formats: | application/json |
Status codes: |
200: OK, A JSON representation of the workflow instance. 404: Not Found, No workflow instance with that identifier exists. |
Returned Entity Schema: | |
Notes: |
|
Testing: |
Sample:
/instance/{id}.json
Testing form (click to reveal)
|
Method / Path: | GET /instance/{id}.xml |
---|---|
Description: | Get a specific workflow instance. |
Path params: | id: The workflow instance identifier |
Optional (query) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, An XML representation of the workflow instance. 404: Not Found, No workflow instance with that identifier exists. |
Returned Entity Schema: | |
Notes: |
|
Testing: |
Sample:
/instance/{id}.xml
Testing form (click to reveal)
|
Method / Path: | GET /mediaPackage/{id}/instances.json |
---|---|
Description: | Returns the workflows for a media package |
Path params: | id: The media package identifier |
Optional (query) params: | NONE |
Response formats: | application/json |
Status codes: | 200: OK, Returns the workflows for a media package. |
Notes: |
|
Testing: |
Sample:
/mediaPackage/{id}/instances.json
Testing form (click to reveal)
|
Write methods
Method / Path: | DELETE /remove/{id} |
---|---|
Description: | Danger! Permenantly removes a workflow instance including all its child jobs. In most circumstances, /stop is what you should use. |
Path params: | id: The workflow instance identifier |
Optional (query) params: | force(Default value=false): If the workflow status should be ignored and the workflow removed anyway |
Response formats: | text/plain |
Status codes: |
204: No Content, If workflow instance could be removed successfully, no content is returned 404: Not Found, No workflow instance with that identifier exists. 403: Forbidden, It's not allowed to remove other workflow instance statues than STOPPED, SUCCEEDED and FAILED (use force parameter to override AT YOUR OWN RISK). |
Notes: |
|
Testing: |
Sample:
/remove/{id}
Testing form (click to reveal)
|
Method / Path: | POST /replaceAndresume |
---|---|
Description: | Replaces a suspended workflow instance with an updated version, and resumes the workflow. |
Path params: | NONE |
Required (form) params: | id: The workflow instance identifier |
Optional (form) params: |
mediapackage:
The new Mediapackage properties: Properties |
Response formats: | text/xml |
Status codes: |
200: OK, An XML representation of the updated and resumed workflow instance. 409: Conflict, Can not resume workflow not in paused state 404: Not Found, No suspended workflow instance with that identifier exists. 401: Unauthorized, You do not have permission to resume. Maybe you need to authenticate. |
Notes: |
|
Testing: |
Sample:
/replaceAndresume
Testing form (click to reveal)
|
Method / Path: | POST /resume |
---|---|
Description: | Resumes a suspended workflow instance. |
Path params: | NONE |
Required (form) params: | id: The workflow instance identifier |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, An XML representation of the resumed workflow instance. 409: Conflict, Can not resume workflow not in paused state 404: Not Found, No suspended workflow instance with that identifier exists. 401: Unauthorized, You do not have permission to resume. Maybe you need to authenticate. |
Notes: |
|
Testing: |
Sample:
/resume
Testing form (click to reveal)
|
Method / Path: | POST /start |
---|---|
Description: | Start a new workflow instance. |
Path params: | NONE |
Required (form) params: |
definition: The workflow definition ID or an XML representation of a workflow definition
mediapackage: The XML representation of a mediapackage |
Optional (form) params: |
parent:
An optional parent workflow instance identifier properties: An optional set of key=value\n properties |
Response formats: | text/xml |
Status codes: |
200: OK, An XML representation of the new workflow instance. 401: Unauthorized, You do not have permission to resume. Maybe you need to authenticate. 404: Not Found, If the parent workflow does not exist |
Returned Entity Schema: | |
Notes: |
|
Testing: |
Sample:
/start
Testing form (click to reveal)
|
Method / Path: | POST /stop |
---|---|
Description: | Stops a workflow instance. |
Path params: | NONE |
Required (form) params: | id: The workflow instance identifier |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, An XML representation of the stopped workflow instance. 404: Not Found, No running workflow instance with that identifier exists. |
Returned Entity Schema: | |
Notes: |
|
Testing: |
Sample:
/stop
Testing form (click to reveal)
|
Method / Path: | POST /suspend |
---|---|
Description: | Suspends a workflow instance. |
Path params: | NONE |
Required (form) params: | id: The workflow instance identifier |
Optional (form) params: | NONE |
Response formats: | text/xml |
Status codes: |
200: OK, An XML representation of the suspended workflow instance. 404: Not Found, No running workflow instance with that identifier exists. |
Notes: |
|
Testing: |
Sample:
/suspend
Testing form (click to reveal)
|
Method / Path: | POST /update |
---|---|
Description: | Updates a workflow instance. |
Path params: | NONE |
Required (form) params: | workflow: The XML representation of the workflow instance. |
Optional (form) params: | NONE |
Status codes: | 204: No Content, Workflow instance updated. |
Notes: |
|
Testing: |
Sample:
/update
Testing form (click to reveal)
|