From f5dcf75075c013bbfdf9cdb6716afee777620c73 Mon Sep 17 00:00:00 2001 From: Jon Bergli Heier Date: Sat, 22 Apr 2017 14:06:35 +0200 Subject: Added upload API. Also updated the API (previously help) page. --- fbin/templates/api.html | 90 ++++++++++++++++++++++++++++++++++++++++++++++++ fbin/templates/base.html | 1 + fbin/templates/help.html | 30 ---------------- 3 files changed, 91 insertions(+), 30 deletions(-) create mode 100644 fbin/templates/api.html delete mode 100644 fbin/templates/help.html (limited to 'fbin/templates') diff --git a/fbin/templates/api.html b/fbin/templates/api.html new file mode 100644 index 0000000..605fedf --- /dev/null +++ b/fbin/templates/api.html @@ -0,0 +1,90 @@ +{% extends "base.html" %} +{% block content %} +

To start using the API you need an API key. +{% if current_user.is_authenticated %} +New keys can be generated using the form below. +There is currently no limit to the number of API keys that can be issued. +

+
+
+ +
+ +
+

+ +

+API keys don't expire, however previously issued API keys can be made unusable by + +them. +

+
+ + Warning! This cannot be undone. +
+ + + Invalidate existing API keys + +
+{% else %} +Please login to generate an API key. +{% endif %} +

+ +

Uploading

+

+HTTP POST to {{ url_for('api.upload', _external = True) }} with the file to be uploaded in the file field. +The regular URL {{ url_for('.upload', _external = True) }} can also be used, but files uploaded via this URL can't be registered to your account as this requires a valid browser session. +

+ +

+cURL example: +

+$ curl -F file=@image.png {{ url_for('api.upload', _external = True) }}
+
+Returns the following JSON, which should be self-explanatory: +
+{
+  "hash": "hash",
+  "status": true,
+  "urls": {
+    "base": "{{ url_for('.file', hash = '', _external = True) }}",
+    "full": "{{ url_for('.file', hash = 'hash', filename = 'image.png', _external = True) }}",
+    "ext": "{{ url_for('.file', hash = 'hash', ext = '.png', _external = True) }}",
+    "hash": "{{ url_for('.file', hash = 'hash', _external = True) }}"
+  }
+}
+
+

+ +

+To register files to your account, the API key must be specified as the bearer token: +

$ curl -H 'Authorization: Bearer api_key' -F file=@image.png {{ url_for('api.upload', _external = True) }}
+(Replace api_key with a generated API key) +

+ +

Legacy upload API

+

+By using the regular URL and adding api=1 you will get machine-readable responses in the form: response result where response is either ERROR or OK, +and result is the file hash in the case of OK, or an error message in the case of ERROR. +The hash can be used to construct URLs in which the paths begin with {{ url_for('.file', hash = 'hash') }} where hash is the hash received. +

+ +

+Any file extension an be appended to the hash, and for convenience the original filename (or whatever filename you prefer) can be appended after an additional slash after the hash. See JSON response above for examples on how to construct URLs. +

+{% endblock %} +{% block scripts %} + + +{% endblock %} diff --git a/fbin/templates/base.html b/fbin/templates/base.html index bab0f7b..dfd6d06 100644 --- a/fbin/templates/base.html +++ b/fbin/templates/base.html @@ -29,6 +29,7 @@ {{ nav_html('.files', 'Files') }} {{ nav_html('.images', 'Images') }} {{ nav_html('.account', 'Account') }} + {{ nav_html('.api', 'API') }} {{ nav_html('.logout', 'Logout') }} {% else %} {{ nav_html('.login', 'Login') }} diff --git a/fbin/templates/help.html b/fbin/templates/help.html deleted file mode 100644 index 899cd78..0000000 --- a/fbin/templates/help.html +++ /dev/null @@ -1,30 +0,0 @@ -{% extends "base.html" %} -{% block content %} -
-

- - TODO: Update this page. -

-
-
- - Everything below this point is outdated and should be disregarded until further notice. -
- -

Usage: POST to $scheme://${host}${settings.virtual_root}u with filedata given to "file" and original filename to "filename". Login is done by generating a login token and sending it as the cookie "token".

-

cURL examples, get_token: -

$ curl $scheme://${host}${settings.virtual_root}a?method=get_token -F username=foo -F password=bar
-{"status": true, "message": null, "method": "get_token", "token": "cb42eb38eb516d9dfcaaa742d1da0b3ad454b2bd05a8b4daa6d01e9587d7c759"}
-Upload using the token: -
$ curl -b 'token=cb42eb38eb516d9dfcaaa742d1da0b3ad454b2bd05a8b4daa6d01e9587d7c759' -F 'file=@image.png' -F 'filename=image.png' -F 'api=1' $scheme://${host}${settings.virtual_root}u
-OK sjLUD
-To expire the current token: -
$ curl $scheme://${host}${settings.virtual_root}a?method=expire_token -F token=cb42eb38eb516d9dfcaaa742d1da0b3ad454b2bd05a8b4daa6d01e9587d7c759
-{"status": true, "message": null, "method": "expire_token"}
-If you get HTTP 417 responses, try adding:-H 'Expect:'.

-

By adding the key-value pair "api=1" you will get machine-readable responses in the form: response result where response is either ERROR or OK, -and result is the file hash in the case of OK, or an error message in the case of ERROR (see example above). -The hash can be used to construct URLs in which the paths begin with /f/hash where hash is the hash received.

-

Any file extension an be appended to the hash, and for convenience the original filename (or whatever filename you prefer) can be appended after an additional slash after the hash.

- -{% endblock %} -- cgit v1.2.3