API documentation. Fixes #30

pages.go

@@ -35,6 +35,13 @@ func pasteHandler(c web.C, w http.ResponseWriter, r *http.Request) {
 	}
 }
 
+func apiDocHandler(c web.C, w http.ResponseWriter, r *http.Request) {
+	err := Templates["api.html"].ExecuteWriter(pongo2.Context{}, w)
+	if err != nil {
+		oopsHandler(c, w, r, RespHTML, "")
+	}
+}
+
 func notFoundHandler(c web.C, w http.ResponseWriter, r *http.Request) {
 	w.WriteHeader(404)
 	err := Templates["404.html"].ExecuteWriter(pongo2.Context{}, w)

server.go

@@ -75,6 +75,7 @@ func setup() {
 	}
 	TemplateSet := pongo2.NewSet("templates", p2l)
 	TemplateSet.Globals["sitename"] = Config.siteName
+	TemplateSet.Globals["siteurl"] = Config.siteURL
 	err = populateTemplatesMap(TemplateSet, Templates)
 	if err != nil {
 		log.Fatal("Error: could not load templates", err)
@@ -93,6 +94,8 @@ func setup() {
 	goji.Get("/", indexHandler)
 	goji.Get("/paste/", pasteHandler)
 	goji.Get("/paste", http.RedirectHandler("/paste/", 301))
+	goji.Get("/API/", apiDocHandler)
+	goji.Get("/API", http.RedirectHandler("/API/", 301))
 
 	if Config.remoteUploads {
 		goji.Get("/upload", uploadRemote)

templates.go

@@ -44,6 +44,7 @@ func populateTemplatesMap(tSet *pongo2.TemplateSet, tMap map[string]*pongo2.Temp
 	templates := []string{
 		"index.html",
 		"paste.html",
+		"api.html",
 		"404.html",
 		"401.html",
 		"oops.html",

templates/API.html

@@ -0,0 +1,93 @@
+{% extends "base.html" %}
+
+{% block head %}
+<link href="/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>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>
+
+			<pre><code>$ curl -T myphoto.jpg {{ siteurl }}upload/  
+{{ siteurl }}myphoto.jpg</code></pre>
+
+			<p>Uploading myphoto.jpg with an expiry of 20 minutes</p>
+
+			<pre><code>$ curl -H &#34;Linx-Expiry: 1200&#34; -T myphoto.jpg {{ siteurl }}upload/
+{{ siteurl }}myphoto.jpg</code></pre>
+
+			<p>Uploading myphoto.jpg with a random filename and getting a json response:</p>
+
+			<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;{{ steurl }}/f34h4iu.jpg&#34;}</code></pre>
+
+			<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>
+
+			<pre><code>$ curl -H &#34;Linx-Delete-Key: mysecret&#34; -X DELETE {{ siteurl }}myphoto.jpg
+DELETED</code></pre>
+
+			<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 %}

templates/base.html

@@ -14,7 +14,8 @@
 			<div id="header">
 				<div id="navigation" class="right">
 					<a href="/">Upload</a> | 
-					<a href="/paste/">Paste</a> 
+					<a href="/paste/">Paste</a> | 
+					<a href="/API/">API</a>
 				</div>
 				<h2><a href="/"  title="{{ sitename }}">{{ sitename }}</a></h2>
 			</div>