Using bepasty’s REST-API¶
The Rest-API enables you to upload and download files, as well as retrieve informations about the file on the server.
Currently (Version 0.3) the REST API provides four API Endpoints:
GET /apis/rest
POST /apis/rest/items
GET /apis/rest/items/<itemname>
GET /apis/rest/items/<itemname>/download
Retrieving information for uploading¶
API Interface:
GET /apis/rest
Example Response:
{
MAX_ALLOWED_FILE_SIZE: 5000000000,
MAX_BODY_SIZE: 1048576
}
This interface will give you important infos for uploading and downloading files to your bepasty server. By now only the MAX_BODY_SIZE will be delivered to you, as no more info is available.
- MAX_BODY_SIZE
- The maximum size of a post request’s body. This is limited by the webserver and other middleware. See the documentation for more information. This also gives you the maximum size for the chunked upload.
- MAX_ALLOWED_FILE_SIZE
- The maximum allowed filesize that can be stored on the server. Files uploads bigger than this limit will be aborted and the file on the server will be deleted.
Uploading a file¶
API Interface:
POST /apis/rest/items
When uploading a file, chunked upload is mandatory. Check the MAX_BODY_SIZE for the maximum chunk size that can be sent to the server. The body of the post request contains the base64 encoded binary of the file to be uploaded.
POST Request by the client¶
- Post Request Body
- Contains the base64 encoded binary of the file to be uploaded.
The following headers can (cursive) or must (bold) be delivered by every post request to the server:
- Content-Range
- The content-range header follows the specification by the w3c (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.16). It has to be provided consistently and can resume a aborted file upload, together with the transaction-ID.
- Transaction-ID
- The transaction-ID will be provided by the server after the first upload chunk. After that first chunk, the transaction-id has to be provided by the client, to continue uploading the file.
- Content-Type
- The content-type of the file uploaded to the server. If the content-type is not given, the server will guess the content-type by the filename. If this fails the content-type will be ‘application/octet-stream’
- Content-Length
- The content-length is mostly ignored by the server. It can be used to indicate the final file size. If your final file size is bigger than the maximum allowed size on the server, the upload will be aborted. The real filesize will be calculated by the server while uploading.
- Content-Filename
- The content-filename header can be used to name the file on the server. If no content-filename is passed, the server will generate a name from scratch. Maximum filename size is 50 characters.
- Maxlife-Unit
The maxlife-unit can be used with the maxlife-value header to define a lifetime for the file that is uploaded. The unit has to be one of these:
['MINUTES', 'HOURS', 'DAYS', 'WEEKS', 'MONTHS', 'YEARS', 'FOREVER']
If this header is ommited the unit will be forever
- Maxlife-Value
- The maxlife-value header defines the value of the maxlife-unit.
POST Response by the server¶
- Transaction-ID
- Transaction-ID provided for continued upload in a chunked upload process.
- Content-Disposition
- The URI of the newly uploaded file on the server. Will only be provided when upload is finished and successful.
Retrieving information about a file¶
API Interface:
GET /apis/rest/items/<itemname>
GET Request by the client¶
- itemname
- The itemname of the file requested.
GET Response by the server¶
Example Respone:
{
file-meta: {
complete: true,
filename: "Wallpaper Work.7z",
hash: "dded24ba6f1d953bedb9d2745635a6f7462817061763b0d70f68b7952722f275",
locked: false,
size: 150225567,
timestamp-download: 1414483078,
timestamp-max-life: -1,
timestamp-upload: 1414443534,
type: "application/x-7z-compressed"
},
uri: "/apis/rest/items/N24bFRZm"
}
- URI
- The URI of the file on the server. Used to link to the download.
- File-Meta
- Filename
- The Filename of the uploaded file.
- Size
- The calculated size of the file on the server.
- Timestamp-Upload
- The timestamp of the moment the file was uploaded.
- Timestamp-Download
- The timestamp of the last download.
- Timestamp-Max_life
- The lifetime timestamp of the file in seconds. -1 means to keep the file forever.
- Complete
- True if the file upload is completed. False if it isn’t
- Locked
- Wether the file is locked or not.
- Hash
- The sha256 hash of the file uploaded. Calculated by the server.
- Type
- Mimetype of the file uploaded. If no filetype is provided this will be set to ‘application/octet-stream’.
Downloading a file¶
API Interface:
GET /apis/rest/items/<itemname>/download
GET Response by the server¶
- Example Response::
- Content-Type: application/x-7z-compressed Content-Length: 150225568 Content-Disposition: attachment; filename=”Wallpaper Work.7z” Content-Range: bytes 0-150225567/150225567
Opens up a stream and delivers the binary data directly. The above headers can be found in the HTTP Response.