Media Upload: Putting Content In

Media upload has two stages, which are described in this section:

• upload request: the media content is actually uploaded to yospaceCDS
• yospaceCDS responds to the upload request synchronously

Note that this only applies to converted content, that is, content that you intend to apply conversion scripts to. Static content-such as fixed logos or banner graphics-is uploaded using regular file transfer (such as SFTP). If you need this facility, ask Yospace to enable it for your account.

Accessing the Web Services APIs

The Web Service APIs described in this document are available from:

To access the Web Service using Secure Sockets Layer (SSL) security, change the http scheme to https.  The WSDL for the Web Service APIs, which may be required for Web Services frameworks such as Java's CXF, is available from:

Upload Request

The media upload service supports the following operations :

• Synchronous upload, inline content: the media content being specified 'inline' i.e. in the webservice request. The webservice response contains a unique ID identifying the content. This should be used to identify the content when you convert it.
• Synchronous upload, referenced content: the media content being specified by a URL where it can be fetched from. yospaceCDS will fetch the content from the specified URL and then responds with a unique ID identifiying the content. This should be used to identify the content when you convert it.
• Asynchronous upload: the media content being uploaded by a subsequent 'content upload' conversion script. The webservice response happens immediately an contains a unique ID under which the content can subsequently be uploaded by the 'asynchronous upload' conversion script. Once this script has completed, the same ID can be used to convert the content. 

Synchronous operations upload the content before the webservice response is returned. This can lead to a significant response delay if the content is large. The asynchronous operation uploads the content as a background process, i.e. the webservice response is returned immediately and a subsequent notification is issued when the content has been uploaded.

Example (synchronous upload, inline content)

This is the example from the earlier section Example Upload Request XML. It shows how an upload request works when the media is included as part of the SOAP message:

<soap:Envelope
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
   
<ns2:contentUploadRequest
       xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
     
<clientApplicationId>petshow</clientApplicationId>
     
<clientApplicationCredentials>Wf</clientApplicationCredentials>
<contentMetaData>
        <key>subject</key>
        <value>dog balancing biscuit on nose</value>
        <key>copyright</key>
        <value>(c) 2008 Acme Dog Films</value>
</contentMetaData>

<content>PSJTYXZlIHRvIGRlbC5pY2lvLnVzIj48aW1nIHNyYz0iaHR0cDovL2RlbC5pY2lvLnVzL2Zhd
mljb24uaWNvIiB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIGFsdD0iZGVsLmljaW8udXMiIGNsYXNzPSJm
YmRfbGlua19zb2NpYWwiLz48L2E+PGENCmhyZWY9Imh0dHA6Ly9yZWRkaXQuY29tL3N1Ym1pd
D91cmw9aHR0cCUzQSUyRiUyRnd3dy5iZWhvbGRlci5jby51ayUyRnBsYW5ldGFy...</content>
     
<addressType>m</addressType>
   
</ns2:contentUploadRequest>
</soap:Body>
</soap:Envelope>

Example Upload (synchronous upload, external content reference with checksum)

This request is identical to the previous example except that the content is not included in the message.  Instead, it is referenced by a URL:

<soap:Envelope
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:contentUploadRequest
        xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
     
<clientApplicationId>petshow</clientApplicationId>  
<clientApplicationCredentials>Wf</clientApplicationCredentials>

<contentMetaData>
        <key>subject</key>
        <value>dog balancing biscuit on nose</value>
        <key>copyright</key>
        <value>(c) 2008 Acme Dog Films</value>   
</contentMetaData>

<externalContentReference>
    http://www.site.com/assets/dog.mov</externalContentReference>
<checksum>d684db594079c87f569fd99fc9c7cfe5</checksum>

<addressType>m</addressType>
   
</ns2:contentUploadRequest>
</soap:Body>
</soap:Envelope>

In this example, the file located at http://www.example.com/assets/dog.mov is fetched by CDS and used as the content.

Example Upload (asynchronous upload)

This request is identical to the previous examples except that no content is included in the message.  Instead, it is expected to be uploaded later by the 'asynchronous upload' conversion script'.   It is strongly recommended that you schedule the upload job within a batch so that its completion triggers further processing.  For a full description of the recommended practice for performing asynchronous uploads, read this chapter.

<soap:Envelope
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ns2:contentUploadRequest
        xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
     
<clientApplicationId>petshow</clientApplicationId>  
<clientApplicationCredentials>Wf</clientApplicationCredentials>

<contentMetaData>
        <key>subject</key>
        <value>dog balancing biscuit on nose</value>
        <key>copyright</key>
        <value>(c) 2008 Acme Dog Films</value>   
</contentMetaData>
     
<addressType>m</addressType>
   
</ns2:contentUploadRequest>
</soap:Body>
</soap:Envelope>

Request Fields

The web request for uploading media can contain the following fields. Several are mandatory—see the following entries for details.

Client Application ID & Credentials

Upload access to yospaceCDS is restricted. When adding content, yospaceCDS will normally require the client’s credentials as an authorised user. Typically this will be a username and an authorisation key. Attempts to submit data with bad or unrecognised credentials will be rejected.

Upload requests should be made over HTTPS or from with a secure VPN to protect this information.

Content Metadata

You can provide additional information about the media content using name/value pairs. This metadata is stored alongside the canonical content. It is not available to end-users. Conversion scripts may use metadata—this depends on the conversion script itself. You must specify metadata if you intend to use a conversion script that needs it.

Media Content

The media content itself is sent with the web request, base-64 encoded within the request XML.

Media Content External Reference

This is the URL of external media content that will be fetched by yospaceCDS. This value is ignored if you have supplied the data inline (using the Media Content field, above). Make sure that the URL is publicly accessible, otherwise yospaceCDS won’t be able to retrieve the content.  The URL can include authentication parameters to fetch content behind HTTP authentication. Use the form http://username:password@hostname/path

Upload Response

When yospaceCDS media farm manager receives a synchronous upload request, the media content is stored and its unique content ID is returned together with an OK status code. For asynchronous requests, a unique content ID is returned (under which content can subsequently be uploaded) together with an OK status code. If there is a problem, a different code is returned (see below).

It is important that you track the notifications sent by yospaceCDS, especially the mapping between the original content (for example, its local filename) and the ID required to access it. Remember that this ID is essential for all your subsequent work with this uploaded content.

Example

This is the example from Example Upload Response XML, showing the response to a successful upload:

<soap:Envelope
   xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
   
<ns2:contentUploadResponse
       xmlns:ns2="http://www.yospace.com/tundra/ContentService/">
     
<contentIdentifier>1/2/3/4/adsd/petshow</contentIdentifier>
     
<status>200</status>
   
</ns2:contentUploadResponse>
</soap:Body>
</soap:Envelope> 

Notification Status Codes

The upload response from yospaceCDS will contain one of the following status codes: