Upload
The upload resource represents data in the state of being uploaded. It is nested under the scope of the resource the data belongs to, for example under a clip.
The following steps are necessary to perform an upload:
- Acquire the URI of the parent resource
- Create the upload, passing the total size.
- Upload the first chunk using the update action.
- Repeat the last step until the entire data has been transferred
The step of splitting the data in chunks is optional. However it is recommended to do so. The chunk size is entirely up to the client application.
Create and Update should requested on a load sharing host: Use webgate-cloud-nn.arri.de where nn is 11,12,13,14,16
All uploads to the main webgate server are cancelled.
| Attributes | |||
|---|---|---|---|
| total_size | Integer | 12345 | Total size of the upload in bytes. |
| current_size | Integer | 1325 | Number of bytes already uploaded. |
| Actions | |||
|---|---|---|---|
| Create | POST | {resource_path}/upload | necessary data: {"total_size": total upload size in bytes (int not string)} |
| Update | PUT | {resource_path}/upload | Header must contain: "Content-Type: application/octet-stream" |
Example
The following requests demonstrate uploading the ASCII data "Hello World !", nested under the fictional resource "/greetings/7". The uploaded can be splitted into chunks. If no chunk number is specified, it is assumed to be the first chunk. The chunk numbering starts with 1.
Step 1: Create upload
Request:
POST /greetings/7/upload HTTP/1.1
Authorization: Bearer example-token
Content-Type: application/json
{"total_size":13}
Response:
HTTP/1.1 201 Created
Step 2: Upload first chunk
Request:
PUT /greetings/7/upload?chunk=1 HTTP/1.1 Authorization: Bearer example-token Content-Type: application/octet-stream Content-Length: 5 Hello
Response:
HTTP/1.1 200 OK
Step 3: Upload second chunk
Request:
PUT /greetings/7/upload?chunk=2 HTTP/1.1 Authorization: Bearer example-token Content-Type: application/octet-stream Content-Length: 6 World
Response:
HTTP/1.1 200 OK
Step 4: Upload last chunk
Request:
PUT /greetings/7/upload?chunk=3 HTTP/1.1 Authorization: Bearer example-token Content-Type: application/octet-stream Content-Length: 2 !
Response:
HTTP/1.1 200 OK
Errors
The following error conditions are defined for uploads:
- 404 in response to: PUT Attempted to upload data before the upload has been created.
- 422 in response to: POST Invalid data passed to the create action (e.g. tried to create an upload of negative size).
- 422 in response to: PUT Attempted to upload more data than specified during create.
Tutorial - Upload a clip into a new playlist
Step 1: Choose a project for the upload!
Request:
GET /api/projects HTTP/1.1 Authorization: Bearer example-token
Response:
HTTP/1.1 200 OK
{
"status": 200,
"status_message": "OK",
"info": "",
"data": {"array":[{"id":6,"name":"Philipp's Project","starts_at":"2013-07-17","ends_at":"2015-01-08"},
{"id":8,"name":"project 3","starts_at":"2011-07-07","ends_at":"2055-01-01"}]}
}
Step 2: Choose a folder for the upload!
Request:
GET /api/projects/6/folders HTTP/1.1 Authorization: Bearer example-token
Response:
HTTP/1.1 200 OK
{
"status": 200,
"status_message": "OK",
"info": "",
"data": {"array":[{"id":1,"name":"philipp","project_id":6,"parent_id":null},
{"id":7,"name":"test 2","project_id":6,"parent_id":null},
{"id":8,"name":"test 3","project_id":6,"parent_id":null},
{"id":129,"name":"Dailies","project_id":6,"parent_id":null},
{"id":257,"name":"another useless folder","project_id":6,"parent_id":null},
{"id":258,"name":"another useless folder","project_id":6,"parent_id":null}]}
}
Step 3: (optional) List child folders of "philipp" (id=1)
Request:
GET /api/projects/6/folders?parent_id=1 HTTP/1.1 Authorization: Bearer example-token
Response:
HTTP/1.1 200 OK
{
"status": 200,
"status_message": "OK",
"info": "",
"data": {"array":[{"id":157,"name":"metadata","project_id":6,"parent_id":1},
{"id":158,"name":"flickr","project_id":6,"parent_id":1},
{"id":163,"name":"file_mass","project_id":6,"parent_id":1},
{"id":223,"name":"galleries","project_id":6,"parent_id":1},
{"id":255,"name":"another useless subfolder","project_id":6,"parent_id":1}]}
}
Step 4: Create a playlist in e.g. "metadata" (id=157)
Request:
POST /api/projects/6/folders/157/playlists HTTP/1.1
Authorization: Bearer example-token
Content-Type: application/json
data: {"name":"how-to-upload"}
Response:
HTTP/1.1 201 Created
{
"status": 201,
"status_message": "Created",
"info": "",
"data": {"playlist":{"id":61441,"name":"how-to-upload","folder_id":157}}
}
Step 5: Create a playlist item in "how-to-upload" (id=61437)
Request:
POST /api/projects/6/folders/157/playlists/61441/items HTTP/1.1
Authorization: Bearer example-token
Content-Type: application/json
data: {"playlist_id":61441}
Response:
HTTP/1.1 201 Created
{
"status": 201,
"status_message": "Created",
"info": "",
"data": {"playlistitem":{"id":1371,"playlist_id":61441,"clip_id":1173,"position":1}}
}
Step 6: Create an upload
Note: To upload the clip, the resource path for the upload is /api/projects/6/clips/1173 and
NOT /api/projects/6/folders/157/playlists/61441/items/1371
Request:
POST /api/projects/6/clips/1167/upload HTTP/1.1
Authorization: Bearer example-token
Content-Type: application/json
data: {"total_size":29533258}
Response:
HTTP/1.1 201 Created
{
"status": 201,
"status_message": "Created",
"info": "",
"data": {"upload":{"current_size":0,"total_size":29533258}}
}
Step 7: Upload the video file
Request:
PUT /api/projects/6/clips/1167/upload HTTP/1.1 Authorization: Bearer example-token Content-Type: application/octet-stream /path/to/video.mp4
cURL example: curl -X PUT localhost:3000/api/projects/6/clips/1169/upload -H "Authorization: Bearer example-token" -H "Content-Type: application/octet-stream" -T "/path/to/video.mp4"
Response:
HTTP/1.1 200 OK
{
"status": 200,
"status_message": "OK",
"info": "",
"data": {"upload":{"current_size":29533258,"total_size":29533258}}
}