Web Services API Reference
This is a summary of the Web Services API to use yospaceCDS as a Transcoding and Archive Hub. Refer to the documentation for details.
Media Upload
Stores content in yospaceCDS. See Media Upload: Putting Content In for more details.
Request Fields
| Field | Description |
|---|---|
| clientApplicationId | Client application ID |
| clientApplicationCredentials | Client application credentials |
| contentMetaData | Content metadata name/value pair(s) [optional] Elements are key and value |
| content | Media content. If media content is not included here, you must provide an external reference instead. |
| externalContentReference | Media content external reference URL. This is the URL from which YospaceCDS will fetch content. It can include authentication parameters to fetch content behind HTTP authentication. Use the form http://username:password@hostname/path |
| addressType | Address type |
Result Codes
| Code | Meaning |
|---|---|
| 200 | OK The upload was successful, and the media content has been stored. The ID for the content (its “canonical” form) is included in the response (as contentIdentifier). |
| 501 | Bad Credentials Your client application isn’t recognised or authorised to upload content into the media farm. |
| 504 | Bad Address Type Typically this must be m (for managed content). |
| 506 | Duplicate An attempt was made to upload media content that is already in YospaceCDS. It has not been stored again, and the ID for the content that was already stored is included in the response. Note that this error will only occur if your account has been configured to check for duplicates. |
| 507 | Missing Media No media content was included in the upload request. |
| 520 | Bad content URL You specified a URL for external content, but it seems to be malformed. |
| 521 | IO Error during content retrieval There was a problem which prevented the external content from being loaded (for example, CDS accessed the external content URL, but received a 404 “missing content“ error). |
| 599 | General Error The upload failed. |
Media Conversion
Makes content available for download, see Media Conversion for more details.
Request Fields
| Field | Description |
|---|---|
| clientApplicationId | Client application ID |
| clientApplicationCredentials | Client application credentials |
| conversionId | Conversion ID |
| restricted | Restricted flag (true or false) |
| scriptParameter | Script parameters (name/value pairs) [optional] Elements are key and value |
| successUrl | Success URL [optional, recommended] |
| failureUrl | Failure URL [optional, recommended] |
| contentIdentifier | Content ID |
| batchParameters | Batch parameters (batch ID and prerequisite jobs) [optional] |
| priority | Priority [optional] |
Result Codes
| Code | Meaning |
|---|---|
| 200 | OK The conversion was successful. Refer to the contentId parameter for the ID of the generated content. |
| 501 | Bad Credentials Your client application isn’t recognised or authorised to apply conversions in the media farm. |
| 503 | Bad Content ID The CDS was unable to find the media content requested. Check that the ID matches the one YospaceCDS supplied when the content was originally uploaded. |
| 504 | Bad Address Type You used an unrecognised address type (normally this should be m). |
| 505 | Contains Invalid Conversion ID The CDS was unable to find the conversion script this request was attempting to run. Check that you’re using the correct conversion ID for this installation. |
| 524 | Bad Batch ID The batchParameters referred to a batch that YospaceCDS could not find. |
| 525 | Client Application Did Not Create This Batch The batchParameters can only add jobs to a batch that you created yourself. |
| 526 | Batch Already Started The batchParameters refer to a batch that has already started, but once a batch is running you cannot add further jobs to it. |
| 527 | Bad Prerequisite Job ID The batchParameters refer to a prerequisite job, but YospaceCDS could find no job with that ID. |
| 528 | Client Application Does Not Own This Content You can only manipulate content that you uploaded yourself. |
| 529 | Maximum Unprocessed Job Limit Reached Each client application has a limit on the number of jobs that can be held, waiting to be run, in the queue. Your current client application’s queue is full. Further attempts to add jobs will be rejected in this way until existing jobs are processed and removed from the queue. |
| 599 | General Error The scheduling of the conversion script failed. |
Batch Jobs
Create Batch Request Fields
| Field | Description |
|---|---|
| clientApplicationId | Client application ID |
| clientApplicationCredentials | Client application credentials |
Create Batch Result Codes
| Code | Meaning |
|---|---|
| 200 | OK The batch was created successfully. Refer to the batchId parameter for the ID of the generated content |
| 501 | Bad Credentials Your client application isn’t recognised or authorised to create batches. |
| 599 | General Error The batch creation failed. |
Start Batch Request Fields
| Field | Description |
|---|---|
| clientApplicationId | Client application ID |
| clientApplicationCredentials | Client application credentials |
| batchId | Batch ID |
Start Batch Response Codes
| Code | Meaning |
|---|---|
| 200 | OK The batch has been started. The jobs it contains will be taken from the queue, with prerequisite jobs being performed first. |
| 501 | Bad Credentials Your client application isn’t recognised or authorised to start batches. |
| 524 | Bad Batch ID The batch ID you provided didn’t match any batches in the queue. |
| 525 | Bad Client Application The Client Application trying to start this batch is not the same as the one that created it. |
| 526 | Batch Already Started The specified batch has already been started. |
| 599 | General Error The batch failed to start. |
Notification URLs
| Field | Appended To | Description |
|---|---|---|
| variant | Success URL | ID for the generated, variant content |
| log | Success & Failure URLS | The log string returned from the processing unit |
| mimetype | Success URL | The MIME type of the content that has been created by the conversion |
Get Content Conversion Status
To enquiry the status of jobs queued for processing, see Get Content Conversion Status for more details.
Request Fields
| Field | Description |
|---|---|
| clientApplicationId | Client application ID |
| clientApplicationCredentials | Client application credentials |
| jobId | Job ID |
Result Codes
| Result | Meaning |
|---|---|
| 200 | Job ID Status Found. The current status of the job is returned in the field jobStatus. See table below for more details. |
| 501 | Bad Credentials |
| 508 | Bad Job ID Important: completed jobs (successful or otherwise) are removed from the queue, and so generate this response. |
| 525 | Client Application does not own this batch |
| 526 | Batch Already Started |
| 599 | General Error |
jobStatus Values
| Job Status Result | Meaning |
|---|---|
| 0 | Pending The job belongs to a batch which has not yet started. The job will not be available for processing until a Start Batch request is issued, and its prerequisite jobs have completed. |
| 1 | Available for Processing The job is on the queue, waiting to be processed. |
| 2 | Requested for Processing The job has been requested by a processor and will be processed immediately. Given the very short time that a job will be in this state, this result is rare. |
| 3 | Processing The processor has begun execution of the job. |
| 4 | Job Succeeded, Still in Queue Typically this indicates that the job has successfully completed but has not been removed from the queue because it is part of a batch which contains other jobs that have not yet completed. |
| 5 | Job Failed, Still in Queue Typically this indicates that the job failed to complete, but has not been removed from the queue because it is part of a batch which contains other jobs that have not yet completed. |
| 6 | Job Succeeded, Notification Failed The job was successfully completed but the notification request failed to reach the success URL. |
| 7 | Job Failed, Notification Failed A right mess! The job failed to complete and the notification request failed to reach the failure URL. |
Content Deletion
Request Fields
| Field | Description |
|---|---|
| clientApplicationId | Client application ID |
| clientApplicationCredentials | Client application credentials |
| contentIdentifier | Content ID |
| addressType | Address Type |
Response Codes
| Code | Meaning |
|---|---|
| 200 | OK Content and all variants successfully deleted. |
| 501 | Bad Credentials |
| 503 | Bad Content ID |
| 504 | Bad Address Type |
| 528 | Client Application is not the owner |
| 599 | General Error |
Variant Deletion
Request Fields
| Field | Description |
|---|---|
| clientApplicationId | Client application ID |
| clientApplicationCredentials | Client application credentials |
| contentIdentifier | Content ID |
| variant | Variant ID |
| restricted | Restricted Flag |
| conversionId | Conversion ID |
| addressType | Address Type |
Response Codes
| Code | Meaning |
|---|---|
| 200 | OK Content and all variants successfully deleted. |
| 501 | Bad Credentials |
| 503 | Bad Content ID |
| 504 | Bad Address Type |
| 528 | Client Application is not the owner |
| 599 | General Error |
Canonical Deletion
Deletes canonical (the original) content, leaving variants intact).Request Fields
| Field | Description |
|---|---|
| clientApplicationId | Client application ID |
| clientApplicationCredentials | Client application credentials |
| contentIdentifier | Content ID |
| addressType | Address Type |
Response Codes
| Code | Meaning |
|---|---|
| 200 | OK Content and all variants successfully deleted. |
| 501 | Bad Credentials |
| 503 | Bad Content ID |
| 504 | Bad Address Type |
| 528 | Client Application is not the owner |
| 599 | General Error |