-
Notifications
You must be signed in to change notification settings - Fork 5
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
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.
The upload url route in the API will accept content in a variety of formats.
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 isoriginal
, atranscoding
or asummary
. Default isoriginal
-
quality
- An integer representing the files relative quality level compared to other files the Resource may contain. Default is0
. -
attributes
- a JSON string containing the key/val attributes that are appropriate for a file w/ the given mimeType -
transcode
- set totrue
orfalse
, but default istrue
. This option only applies in cases where the files representation isoriginal
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,
}
}
]
}
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.
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"
}
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