linx-server/templates/API.html

154 lines
6.3 KiB
HTML

{% extends "base.html" %}
{% block title %}{{sitename}} - API{% endblock %}
{% block head %}
<link href="{{ sitepath }}static/css/github-markdown.css" rel="stylesheet" type="text/css">
{% endblock %}
{% block content %}
<div id="main">
<div id='inner_content'>
<div class="normal markdown-body">
<h2>API</h2>
<h3>Client</h3>
<p>To simplify uploading and deleting files, you can use <a target="_blank"
href="https://github.com/andreimarcu/linx-client">linx-client</a>, which uses this API.</p>
{% if auth != "none" %}
<h3>Keys</h3>
<p>This instance uses API Keys, therefore you will need to provide a key for uploading and deleting
files.<br /> To do so, add the <code>Linx-Api-Key</code> header with your key.</p>
{% endif %}
<h3>Uploading a file</h3>
<p>To upload a file, make a PUT request to <code>{{ siteurl }}upload/</code> and you will get the url of
your upload back.</p>
<p><strong>Optional headers with the request</strong></p>
{% if not forcerandom %}
<p>Randomize the filename<br />
<code>Linx-Randomize: yes</code></p>
{% endif %}
<p>Specify a custom deletion key<br />
<code>Linx-Delete-Key: mysecret</code></p>
<p>Protect file with password<br />
<code>Linx-Access-Key: mysecret</code></p>
<p>Specify an expiration time (in seconds)<br />
<code>Linx-Expiry: 60</code></p>
<p>Get a json response<br />
<code>Accept: application/json</code></p>
<p>The json response will then contain:</p>
<blockquote>
<p>“url”: the publicly available upload url<br />
“direct_url”: the url to access the file directly<br />
“filename”: the (optionally generated) filename<br />
“delete_key”: the (optionally generated) deletion key,<br />
“access_key”: the (optionally supplied) access key,<br />
“expiry”: the unix timestamp at which the file will expire (0 if never)<br />
“size”: the size in bytes of the file<br />
“mimetype”: the guessed mimetype of the file<br />
“sha256sum”: the sha256sum of the file,</p>
</blockquote>
<p><strong>Examples</strong></p>
<p>Uploading myphoto.jpg</p>
{% if auth != "none" %}
<pre><code>$ curl -H &#34;Linx-Api-Key: mysecretkey&#34; -T myphoto.jpg {{ siteurl }}upload/
{{ siteurl }}{% if not forcerandom %}myphoto.jpg{% else %}7z4h4ut.jpg{% endif %}</code></pre>
{% else %}
<pre><code>$ curl -T myphoto.jpg {{ siteurl }}upload/
{{ siteurl }}{% if not forcerandom %}myphoto.jpg{% else %}wtq7pan.jpg{% endif %}</code></pre>
{% endif %}
<p>Uploading myphoto.jpg with an expiry of 20 minutes</p>
{% if auth != "none" %}
<pre><code>$ curl -H &#34;Linx-Api-Key: mysecretkey&#34; -H &#34;Linx-Expiry: 1200&#34; -T myphoto.jpg {{ siteurl }}upload/
{{ siteurl }}{% if not forcerandom %}myphoto.jpg{% else %}jm295snf.jpg{% endif %}</code></pre>
{% else %}
<pre><code>$ curl -H &#34;Linx-Expiry: 1200&#34; -T myphoto.jpg {{ siteurl }}upload/
{{ siteurl }}{% if not forcerandom %}myphoto.jpg{% else %}1doym9u2.jpg{% endif %}</code></pre>
{% endif %}
<p>Uploading myphoto.jpg with a random filename and getting a json response:</p>
{% if auth != "none" %}
<pre><code>$ curl -H &#34;Linx-Api-Key: mysecretkey&#34; -H &#34;Accept: application/json&#34;{% if not forcerandom %} -H &#34;Linx-Randomize: yes&#34;{% endif %} -T myphoto.jpg {{ siteurl }}upload/
{&#34;delete_key&#34;:&#34;...&#34;,&#34;expiry&#34;:&#34;0&#34;,&#34;filename&#34;:&#34;f34h4iu.jpg&#34;,&#34;mimetype&#34;:&#34;image/jpeg&#34;,
&#34;sha256sum&#34;:&#34;...&#34;,&#34;size&#34;:&#34;...&#34;,&#34;url&#34;:&#34;{{ siteurl }}f34h4iu.jpg&#34;}</code></pre>
{% else %}
<pre><code>$ curl -H &#34;Accept: application/json&#34;{% if not forcerandom %} -H &#34;Linx-Randomize: yes&#34;{% endif %} -T myphoto.jpg {{ siteurl }}upload/
{&#34;delete_key&#34;:&#34;...&#34;,&#34;expiry&#34;:&#34;0&#34;,&#34;filename&#34;:&#34;f34h4iu.jpg&#34;,&#34;mimetype&#34;:&#34;image/jpeg&#34;,
&#34;sha256sum&#34;:&#34;...&#34;,&#34;size&#34;:&#34;...&#34;,&#34;url&#34;:&#34;{{ siteurl }}f34h4iu.jpg&#34;}</code></pre>
{% endif %}
<h3>Overwriting a file</h3>
<p>To overwrite a file you uploaded, simply provide the <code>Linx-Delete-Key</code> header with the
original file's deletion key.</p>
<p><strong>Example</p></strong>
<p>To overwrite myphoto.jpg</p>
{% if auth != "none" %}
<pre><code>$ curl -H &#34;Linx-Api-Key: mysecretkey&#34; -H &#34;Linx-Delete-Key: mysecret&#34; -T myphoto.jpg {{ siteurl }}upload/
{{ siteurl }}myphoto.jpg</code></pre>
{% else %}
<pre><code>$ curl -H &#34;Linx-Delete-Key: mysecret&#34; -T myphoto.jpg {{ siteurl }}upload/
{{ siteurl }}myphoto.jpg</code></pre>
{% endif %}
<h3>Deleting a file</h3>
<p>To delete a file you uploaded, make a DELETE request to <code>{{ siteurl }}yourfile.ext</code> with the
delete key set as the <code>Linx-Delete-Key</code> header.</p>
<p><strong>Example</strong></p>
<p>To delete myphoto.jpg</p>
{% if auth != "none" %}
<pre><code>$ curl -H &#34;Linx-Api-Key: mysecretkey&#34; -H &#34;Linx-Delete-Key: mysecret&#34; -X DELETE {{ siteurl }}myphoto.jpg
DELETED</code></pre>
{% else %}
<pre><code>$ curl -H &#34;Linx-Delete-Key: mysecret&#34; -X DELETE {{ siteurl }}myphoto.jpg
DELETED</code></pre>
{% endif %}
<h3>Information about a file</h3>
<p>To retrieve information about a file, make a GET request the public url with
<code>Accept: application/json</code> headers and you will receive a json response containing:</p>
<blockquote>
<p>“url”: the publicly available upload url<br />
“direct_url”: the url to access the file directly<br />
“filename”: the (optionally generated) filename<br />
“expiry”: the unix timestamp at which the file will expire (0 if never)<br />
“size”: the size in bytes of the file<br />
“mimetype”: the guessed mimetype of the file<br />
“sha256sum”: the sha256sum of the file,</p>
</blockquote>
<p><strong>Example</strong></p>
<pre><code>$ curl -H &#34;Accept: application/json&#34; {{ siteurl }}myphoto.jpg
{&#34;expiry&#34;:&#34;0&#34;,&#34;filename&#34;:&#34;myphoto.jpg&#34;,&#34;mimetype&#34;:&#34;image/jpeg&#34;,&#34;sha256sum&#34;:&#34;...&#34;,&#34;size&#34;:&#34;...&#34;}</code></pre>
</div>
</div>
</div>
{% endblock %}