Uploading Content

Uploading content for a Resource is a two-step process. Before the exact content can be specified, the containing Resource must actually exist. The main reason for this is to ensure that the API data does not get out of sync by accepting files or other content, without knowing exactly where it should belong. Practically what this means is that you will make a call to the API to create a Resource, and then you make a follow-up call to a different route to set the content of the Resource. For example:

• POST /resources creates Resource 1
• POST /resources/1/content/some-23-unique-1234-token-1234 sets the Resources content

Upload URLs

When a Resource is created, you'll notice an extra property returned in the response. For example:

POST /resources&_format=yml will return:

resource:
    #resource data
contentUploadUrl: "http://api.ayamel.org/api/v1/resources/123456/content/1234567890"
response:
    code: 201
    message: Created

The extra contentUploadUrl is the API route that you will POST your content to. These URLs are one-time use, and they expire after one hour. If you need to change content already uploaded for a Resource, or upload the content after expiration, you can request a new upload url via a call to GET /resources/{id}/request-upload-url.

In the upload url you'll notice an extra token at the end. This is a security token created when the upload url was generated. We do this because it allows us to verify that the url was created by someone who is authenticated to upload content in the first place, but it lets you use the URL from anywhere without further verification. It's a bit technical, but what it enables is for clients to post files directly from their browser to the media API, without first having to send them via an intermediate server.

Content formats

The upload url route in the API will accept content in a variety of formats.

Uploading a file

To upload a file, you need to set the file post field. Ideally you should set all headers that would be set by a browser uploading the file, for example specifying its size, and mime type.

In addition to actually sending the file, you can set other post fields as well, all of which are optional:

• mime - A full mime string, which can contain more than just the type.
• mimeType - The mime type. This is mostly useful for various text formats that would be reported as text/plain by default, but do have a more specific mimeType that many programs may not be aware of.
• representation - Whether the file is original, a transcoding or a summary. Default is original
• quality - An integer representing the files relative quality level compared to other files the Resource may contain. Default is 0.
• attributes - a JSON string containing the key/val attributes that are appropriate for a file w/ the given mimeType
• transcode - set to true or false, but default is true. This option only applies in cases where the files representation is original

Specify remote files

In this scenario, you post a json object that specifies exactly what the array of files should be in the Resources content. The API will verify that the files actually exist, or return an error.

POST: /resources/{id}/content/{token}:

{
    "remoteFiles": [
        {
            "downloadUri": "http://example.com/files/some_video_original.wmv",
            "mime": "video/x-ms-wmv",
            "mimeType": "video/x-ms-wmv",
            "representation": "original",
            "quality": 1,
            "bytes": 14658,
            "attributes": {
                "duration": 300,
                "frameSize": {"width":720,"height":480},
                "frameRate": 48,
                "bitrate": 44000,
            }
         },
         {
            "downloadUri": "http://example.com/files/transcoded.mp4",
            "mime": "video/mp4",
            "mimeType": "video/mp4",
            "representation": "transcoding",
            "quality": 1,
            "bytes": 9600,
            "attributes": {
                "duration": 300,
                "frameSize": {"width":720,"height":480},
                "frameRate": 48,
                "bitrate": 36000,
            }
         }
    ]
}

An external uri

In this scenario, you POST a json object that specifies the uri of a file that exists elsewhere. If any Resource fields can be determined from this file, which are not already set, they will be set.

POST /resources/{id}/content/{token}:

{
    "uri": "http://www.example.com/files/some_file.mp3"
}

A note: Only http and https schemes are supported.

A YouTube video

This is actually the same as specifying an external uri, but you use a custom uri scheme. The difference is that the API will actually use YouTube's API to retrieve data, and set any unset fields that may be available, as well as store references to the video content hosted on YouTube.

{
    "uri": "youtube://txqiwrbYGrs"
}

Replace or append content

On any call to the upload route, you can specify the replace parameter, which defaults to true. When content is uploaded for a Resource, previously existing content references are removed by default. If, however, you want to append new items, like new file uploads, and keep the files that the Resource already has, just specify replace=false.

POST /resources/{id}/content/{token}?replace=false