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 /agents/{name}.{format:xml|json}
- GET /agents/{name}/capabilities.{type:xml|json}
- GET /agents/{name}/configuration.{type:xml|json}
- GET /recordings
- GET /agents.{type:xml|json}
- GET /recordings/{id}.{type:xml|json|}
- DELETE /agents/{name}
- DELETE /recordings/{id}
- POST /agents/{name}
- POST /agents/{name}/configuration
- POST /recordings/{id}
Read methods
| Method / Path: | GET /agents/{name}.{format:xml|json} |
|---|---|
| Description: | Return the state of a given capture agent |
| Path params: |
name:
Name of the capture agent format: The output format (json or xml) of the response body. |
| Optional (query) params: | NONE |
| Response formats: |
application/xml
application/json |
| Status codes: |
200: OK, {agentState} 404: Not Found, The agent {agentName} does not exist 405: Method Not Allowed, If the {format} is not xml or json 503: Service Unavailable, iCapture agent state service unavailable |
| Testing: |
Sample:
/agents/{name}.{format:xml|json}
Testing form (click to reveal)
|
| Method / Path: | GET /agents/{name}/capabilities.{type:xml|json} |
|---|---|
| Description: | Return the capabilities of a given capture agent |
| Path params: |
name:
Name of the capture agent type: The Document type |
| Optional (query) params: | NONE |
| Response formats: |
text/xml
application/json |
| Status codes: |
200: OK, An XML representation of the agent capabilities 404: Not Found, The agent {name} does not exist in the system |
| Testing: |
Sample:
/agents/{name}/capabilities.{type:xml|json}
Testing form (click to reveal)
|
| Method / Path: | GET /agents/{name}/configuration.{type:xml|json} |
|---|---|
| Description: | Return the configuration of a given capture agent |
| Path params: |
name:
Name of the capture agent type: The Document type |
| Optional (query) params: | NONE |
| Response formats: |
text/xml
application/json |
| Status codes: |
200: OK, An XML or JSON representation of the agent configuration 404: Not Found, The agent {name} does not exist in the system |
| Testing: |
Sample:
/agents/{name}/configuration.{type:xml|json}
Testing form (click to reveal)
|
| Method / Path: | GET /recordings |
|---|---|
| Description: | Return all registered recordings and their state |
| Path params: | NONE |
| Optional (query) params: | NONE |
| Response formats: | text/xml |
| Status codes: | 200: OK, Returns all known recordings. |
| Testing: |
Sample:
/recordings
/capture-admin/recordings
|
| Method / Path: | GET /agents.{type:xml|json} |
|---|---|
| Description: | Return all of the known capture agents on the system |
| Path params: | type: The Document type |
| Optional (query) params: | NONE |
| Response formats: |
text/xml
application/json |
| Status codes: | 200: OK, An XML representation of the agent capabilities |
| Testing: |
Sample:
/agents.{type:xml|json}
Testing form (click to reveal)
|
| Method / Path: | GET /recordings/{id}.{type:xml|json|} |
|---|---|
| Description: | Return the state of a given recording |
| Path params: |
id:
The ID of a given recording type: The Documenttype |
| Optional (query) params: | NONE |
| Response formats: |
text/xml
application/json |
| Status codes: |
200: OK, Returns the state of the recording with the correct id 404: Not Found, The recording with the specified ID does not exist |
| Testing: |
Sample:
/recordings/{id}.{type:xml|json|}
Testing form (click to reveal)
|
Write methods
| Method / Path: | DELETE /agents/{name} |
|---|---|
| Description: | Remove record of a given capture agent |
| Path params: | name: Name of the capture agent |
| Optional (query) params: | NONE |
| Response formats: | text/html |
| Status codes: |
200: OK, {agentName} removed 404: Not Found, The agent {agentname} does not exist |
| Testing: |
Sample:
/agents/{name}
Testing form (click to reveal)
|
| Method / Path: | DELETE /recordings/{id} |
|---|---|
| Description: | Remove record of a given recording |
| Path params: | id: The ID of a given recording |
| Optional (query) params: | NONE |
| Status codes: |
200: OK, {id} removed 400: Bad Request, {id} is empty 404: Not Found, Recording with {id} could not be found |
| Testing: |
Sample:
/recordings/{id}
Testing form (click to reveal)
|
| Method / Path: | POST /agents/{name} |
|---|---|
| Description: | Set the status of a given capture agent |
| Path params: | name: Name of the capture agent |
| Required (form) params: | state: The state of the capture agent. Known states are: idle, shutting_down, capturing, uploading, unknown, offline, error |
| Optional (form) params: | address: Address of the agent |
| Response formats: | text/html |
| Status codes: |
200: OK, {agentName} set to {state} 400: Bad Request, {state} is empty or not known 503: Service Unavailable, Capture agent state service not available |
| Testing: |
Sample:
/agents/{name}
Testing form (click to reveal)
|
| Method / Path: | POST /agents/{name}/configuration |
|---|---|
| Description: | Set the configuration of a given capture agent, registering it if it does not exist |
| Path params: | name: Name of the capture agent |
| Required (form) params: | configuration: An XML or JSON representation of the capabilities. XML as specified in http://java.sun.com/dtd/properties.dtd (friendly names as keys, device locations as corresponding values) |
| Optional (form) params: | NONE |
| Response formats: |
text/xml
application/json |
| Status codes: |
200: OK, An XML or JSON representation of the agent configuration 400: Bad Request, The configuration format is incorrect OR the agent name is blank or null |
| Testing: |
Sample:
/agents/{name}/configuration
Testing form (click to reveal)
|
| Method / Path: | POST /recordings/{id} |
|---|---|
| Description: | Set the status of a given recording, registering it if it is new |
| Path params: | id: The ID of a given recording |
| Required (form) params: | state: The state of the recording. Known states: unknown, capturing, capture_finished, capture_error, manifest, manifest_error, manifest_finished, compressing, compressing_error, uploading, upload_finished, upload_error. |
| Optional (form) params: | NONE |
| Status codes: |
200: OK, {id} set to {state} 400: Bad Request, {id} or {state} is empty or {state} is not known 404: Not Found, Recording with {id} could not be found |
| Testing: |
Sample:
/recordings/{id}
Testing form (click to reveal)
|