Added upload API.

Also updated the API (previously help) page.

1 files changed, 90 insertions, 0 deletions

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 %}
+<p>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.
+</p>
+<div class="input-group">
+	<div class="input-group-btn">
+		<button type="button" class="btn btn-default" onclick="generate_api_key(event)">
+			<span class="glyphicon glyphicon-refresh" aria-hidden="true"></span>
+			Generate
+		</button>
+	</div>
+	<input type="text" id="api-key" class="form-control" aria-label="API key" placeholder="API key">
+</div>
+</p>
+
+<p>
+API keys don't expire, however previously issued API keys can be made unusable by
+<a href="#invalidate-collapse" data-toggle="collapse" aria-expanded="false" aria-controls="invalidate-collapse">invalidating</a>
+them.
+<div class="collapse" id="invalidate-collapse">
+	<div class="alert alert-danger">
+		<span class="glyphicon glyphicon-danger" aria-hidden="true"></span>
+		<strong>Warning!</strong> This cannot be undone.
+	</div>
+	<a href="{{ url_for('.invalidate_api_keys') }}" role="button" class="btn btn-danger">
+		<span class="glyphicon glyphicon-remove" aria-hidden="true"></span>
+		Invalidate existing API keys
+	</a>
+</div>
+{% else %}
+Please <a href="{{ url_for('.login') }}">login</a> to generate an API key.
+{% endif %}
+</p>
+
+<h2>Uploading</h2>
+<p>
+HTTP POST to <code>{{ url_for('api.upload', _external = True) }}</code> with the file to be uploaded in the <code>file</code> field.
+The regular URL <code>{{ url_for('.upload', _external = True) }}</code> can also be used, but files uploaded via this URL can't be registered to your account as this requires a valid browser session.
+</p>
+
+<p>
+cURL example:
+<pre>
+$ curl -F file=@image.png {{ url_for('api.upload', _external = True) }}
+</pre>
+Returns the following JSON, which should be self-explanatory:
+<pre>
+{
+  "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) }}"
+  }
+}
+</pre>
+</p>
+
+<p>
+To register files to your account, the API key must be specified as the bearer token:
+<pre>$ curl -H 'Authorization: Bearer <em>api_key</em>' -F file=@image.png {{ url_for('api.upload', _external = True) }}</pre>
+(Replace <em>api_key</em> with a generated API key)
+</p>
+
+<h3>Legacy upload API</h3>
+<p>
+By using the regular URL and adding <code>api=1</code> you will get machine-readable responses in the form: <code>response result</code> where <code>response</code> is either <code>ERROR</code> or <code>OK</code>,
+and <code>result</code> is the file hash in the case of <code>OK</code>, or an error message in the case of <code>ERROR</code>.
+The hash can be used to construct URLs in which the paths begin with <code>{{ url_for('.file', hash = 'hash') }}</code> where <code>hash</code> is the hash received.
+</p>
+
+<p>
+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.
+</p>
+{% endblock %}
+{% block scripts %}
+<script src="{{ url_for('static', filename = 'js/bootstrap.min.js') }}"></script>
+<script>
+function generate_api_key(event) {
+	$.get('{{ url_for('.generate_api_key') }}', function(data) {
+		$('#api-key').val(data);
+	});
+}
+</script>
+{% endblock %}