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:

  1. Acquire the URI of the parent resource
  2. Create the upload, passing the total size.
  3. Upload the first chunk using the update action.
  4. 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.
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}}
}