Upload

files

This relation targets the collection of file upload.

Keepeek API provides two methods for file upload:

• Single request upload for small files (<=20MB)
• Chunked and resumable upload for large files

Single request file upload

Send a POST (create) request on the file upload collection: http://baobab.keepeek.com/api/dam/files

Binary content of the file is transferred in the request body.

Maximum file size this upload method support is 50MB but it is more reasonable to limit its use to small file (<=20MB) as some browser does not provides upload progress information.

Client must provide the following headers:

• Content-Length
• Content-Type

And either :

• X-KPK-Base64FileName, Keepeek custom HTTP header to send base64 file name (strongly recommended)

Or

• X-KPK-FileName, Keepeek custom HTTP header to send the original file name (ISO-8859-1)

Sample request:

POST http://baobab.keepeek.com/api/dam/files
X-KPK-FileName: test.jpg
Content-Type: image/jpeg
Content-Length: 12314564

<test.jpg content>

If the upload is successful, the API returns a 201 Created status code and a file descriptor.

Sample response:

HTTP/1.1 201 Created
Location: http://baobab.keepeek.com/api/dam/files/df1234ac
Content-Type: application/json+hal,[...]

{
  "id":"df1234ac",
  "expirationDate":"2015-01-29T09:21:55.523Z",
  "fileName":"test.jpg",
  "fileContentType":"image/jpeg",
  "size":"12314564",
  "_links":{"self":"http://baobab.keepeek.com/api/dam/files/df1234ac"}
}

Client application can reuse this file descriptor for further usage like create media or replace original file for an existing media...

/!\ The lifetime of an uploaded file is short, therefore do not store file descriptor for a long time and use it to create or update long lived resources like media. The expiration date is not guaranteed by the API as temporary files may be wiped for maintenance purpose.

Chunked and resumable file upload

For chunk upload:

• Send an empty POST (create) request on the file upload collection: http://baobab.keepeek.com/api/dam/files
• Send PUT request for each chunk to the file descriptor location: http://baobab.keepeek.com/api/dam/files/arru58g9

First call is similar to the single call file upload with following changes:

• request body has no content Content-Length: 0
• file to upload content type and length are transmitted in the custom headers X-KPK-Upload-Content-Type and X-KPK-Upload-Content-Length

POST http://baobab.keepeek.com/api/dam/files
X-KPK-FileName: test.mp4
X-KPK-Upload-Content-Type: video/mp4
X-KPK-Upload-Content-Length: 535010012
Content-Length: 0

HTTP/1.1 201 Created
Location: http://baobab.keepeek.com/api/dam/files/5fa23b4ac
Content-Type: application/json

{
  "id":"5fa23b4ac",
  "expirationDate":"2015-01-29T09:21:55.523Z",
  "fileName":"test.mp4",
  "fileContentType":"video/mp4",
  "size":"535010012",
  "nextExpectedRanges": ["0-"],
  "_links":{"self":"http://baobab.keepeek.com/api/dam/files/5fa23b4ac"}
}

Response lists the next expected range and provides the file descriptor location

Client application can send chunk of the file by sending PUT requests with Content-Range header

PUT http://baobab.keepeek.com/api/dam/files/5fa23b4ac
Content-Length: 20000000
Content-Range: bytes 0-19999999/535010012

<test.mp4 content (20 first Mb)>

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "id":"5fa23b4ac",
  "expirationDate":"2015-01-29T09:21:55.523Z",
  "fileName":"test.mp4",
  "fileContentType":"video/mp4",
  "size":"535010012",
  "nextExpectedRanges": ["20000000-"],
  "_links":{"self":"http://baobab.keepeek.com/api/dam/files/5fa23b4ac"}
}

API returns following status code:

• 202 Accepted when chunk is processed
• 200 Ok when the last chunk has been processed

If the client send invalid chunks API returns 416 error code.

4.31.0+

Send a GET request to get next expected ranges. It could be useful when API post return 416 error code (416 Range Not Satisfiable), to resume an upload. For example, in case of connection break.

4.0.0+