Figshare Upload Service
Uploads API
Upload status
An upload status can be:
PENDING
- waiting for it's parts to be uploadedCOMPLETED
- all parts were uploaded and the file was assembled on the storageABORTED
- canceled for some reason(user request, timeout, error)
Endpoints
GET /upload/<token>
- get upload info
Response:
Status Code | Explanation | Body |
---|---|---|
200 OK | all good | explained below |
500 Internal Server Error | internal error | empty |
404 Not Found | unknown upload token | empty |
200 OK
Body:
js
{
token: "upload-token",
name: "my-file.zip",
size: 10249281,
md5: "filemd5", // as provided on upload creation
status: "PENDING",
parts: [
{
// upload parts -- see parts API for representation
}
]
}
Parts API
Part status
PENDING
-- part is ready to be uploadedCOMPLETE
-- part data has been complete and saved to storage
Part locking
When a part is being uploaded it is being locked, by setting the
locked
flag to true. No changes/uploads can happen on this part from
other requests.
Byte ranges
The part range is specified by startOffset
and endOffset
. They
indexes zero-based and inclusive. Example:
Given:
- the following file data: "abcdefghij"
part1
withstartOffset=0
andendOffset=3
part2
withstartOffset=4
andendOffset=7
Then:
part1
isabcd
part2
isefgh
Endpoints
GET /upload/<token>/<part_no>
- get part info
Responses:
Status Code | Explanation | Body |
---|---|---|
200 OK | all good | explained below |
500 Internal Server Error | internal error | empty |
404 Not Found | unknown upload token or part number | empty |
200 OK
Body:
js
{
partNo: 3,
startOffset: 1024,
endOffset: 2047,
status: "PENDING",
locked: false
}
PUT /upload/<token>/<part_no>
- receives part data
The entire body of the request is piped as-is to S3. It is assumed that the
body is the correct piece of the file, from startOffset
to endOffset
While this requests is being processed the part is going to be in a
locked state. The request can end with a 409
status code if a
lock for the part could not be obtained.
Warning if content length is less than part size the request will timeout
Responses:
Status Code | Explanation | Body |
---|---|---|
200 OK | all good | explained below |
500 Internal Server Error | internal error | empty |
404 Not Found | unknown upload token or part number | empty |
409 Conflict | part data cannot be uploaded | empty |
200 OK
DELETE /upload/<token>/<part_no>
- reset part data
This will reset the part to it's PENDING
state and remove any
storage meta.
Responses:
Status Code | Explanation | Body |
---|---|---|
200 Accepted | all good | empty |
500 Internal Server Error | internal error | empty |
404 Not Found | unknown upload token or part number | empty |
409 Conflict | upload completed or part locked | empty |