ProfouzorsLinx/templates/API.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 %}