1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
|
========================
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 the REST API provides the following API Endpoints::
GET /apis/rest
GET /apis/rest/items
POST /apis/rest/items
GET /apis/rest/items/<itemname>
GET /apis/rest/items/<itemname>/download
POST /apis/rest/items/<itemname>/modify
POST /apis/rest/items/<itemname>/delete
POST /apis/rest/items/<itemname>/lock
POST /apis/rest/items/<itemname>/unlock
Authentication
==============
For endpoints that require non-default permissions, authentication can be done through http basic authentication. The user is ignored and the password is the key for the intended permissions.
Errors
======
The error response from REST-API will set ``Content-Type:
application/json``, and body as JSON format like the following
example. (it was previously ``Content-Type: text/html; charset=utf-8``
and partial HTML page or plain string)
Example::
{
"error": {
"code": <HTTP status code>,
"message": "<error detail>"
}
}
Retrieving information for uploading
====================================
API Interface:
::
GET /apis/rest
GET Response by the server:
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. (required permission:
:ref:`create <permissions>`)
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 omitted 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-Location*
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>
(required permission: :ref:`read <permissions>`)
GET Request by the client:
**itemname**
The itemname of the file requested.
GET Response by the server:
Example Response::
{
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*
Whether 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'.
Retrieving Item List
====================
API Interface:
::
GET /apis/rest/items
(required permission: :ref:`list <permissions>`)
GET Request by the client:
No Parameters
GET Response by the server:
Example Response::
{
"N24bFRZm": {
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"
}, ...
}
Parameters are the same as in *Retrieving information about a file*.
Downloading a file
==================
API Interface:
::
GET /apis/rest/items/<itemname>/download
(required permission: :ref:`read <permissions>`)
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.
Modifying metadata
==================
API Interface:
::
POST /apis/rest/items/<itemname>/modify
Modify metadata specified by ``<itemname>``. (required permission:
:ref:`modify <permissions>`)
POST Request by the client:
**itemname**
The itemname of the target file.
**Content-Type**
The content-type header must be ``application/json``
New metadata is specified by JSON in the request body. Currently
this API is supporting to modify ``filename`` and ``type``. For
example, if you want to modify the filename::
{"filename": "new-filename.txt"}
if you want to modify both filename and type::
{"filename": "new-filename.txt", "type": "new-mimetype"}
POST Response by the server:
On success, status code == 200. Otherwise status code != 200.
Deleting a file
===============
API Interface:
::
POST /apis/rest/items/<itemname>/delete
Delete a file specified by ``<itemname>``. (required permission:
:ref:`delete <permissions>`)
POST Request by the client:
**itemname**
The itemname of the target file.
POST Response by the server:
On success, status code == 200. Otherwise status code != 200.
Locking a file
==============
API Interface:
::
POST /apis/rest/items/<itemname>/lock
Lock a file specified by ``<itemname>``. (required permission:
:ref:`admin <permissions>`)
POST Request by the client:
**itemname**
The itemname of the target file.
POST Response by the server:
On success, status code == 200. Otherwise status code != 200.
Unlocking a file
================
API Interface:
::
POST /apis/rest/items/<itemname>/unlock
Lock a file specified by ``<itemname>``. (required permission:
:ref:`admin <permissions>`)
POST Request by the client:
**itemname**
The itemname of the target file.
POST Response by the server:
On success, status code == 200. Otherwise status code != 200.
|
