linx-server/templates/API.html

{% extends "base.html" %}

{% 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 using_auth %}
			<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>

			<p>Randomize the filename<br/>
			<code>Linx-Randomize: yes</code></p>

			<p>Specify a custom deletion key<br/>
			<code>Linx-Delete-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/>
			 “filename”:   the (optionally generated) filename<br/>
			 “delete_key”: the (optionally generated) deletion 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 using_auth %}
			<pre><code>$ curl -H &#34;Linx-Api-Key: mysecretkey&#34; -T myphoto.jpg {{ siteurl }}upload/  
{{ siteurl }}myphoto.jpg</code></pre>
			{% else %}
			<pre><code>$ curl -T myphoto.jpg {{ siteurl }}upload/  
{{ siteurl }}myphoto.jpg</code></pre>
			{% endif %}

			<p>Uploading myphoto.jpg with an expiry of 20 minutes</p>

			{% if using_auth %}
			<pre><code>$ curl -H &#34;Linx-Api-Key: mysecretkey&#34; -H &#34;Linx-Expiry: 1200&#34; -T myphoto.jpg {{ siteurl }}upload/
{{ siteurl }}myphoto.jpg</code></pre>
			{% else %}
			<pre><code>$ curl -H &#34;Linx-Expiry: 1200&#34; -T myphoto.jpg {{ siteurl }}upload/
{{ siteurl }}myphoto.jpg</code></pre>
			{% endif %}

			<p>Uploading myphoto.jpg with a random filename and getting a json response:</p>

			{% if using_auth %}
			<pre><code>$ curl -H &#34;Linx-Api-Key: mysecretkey&#34; -H &#34;Accept: application/json&#34; -H &#34;Linx-Randomize: yes&#34; -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; -H &#34;Linx-Randomize: yes&#34; -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 using_auth %}
			<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 using_auth %}
			<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/>
			 “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 %}