From 62443e984d7f85a0cb049c61f6fb7b259a527248 Mon Sep 17 00:00:00 2001 From: andreimarcu Date: Thu, 8 Oct 2015 21:48:06 -0400 Subject: [PATCH] API documentation. Fixes #30 --- pages.go | 7 ++++ server.go | 3 ++ templates.go | 1 + templates/API.html | 93 +++++++++++++++++++++++++++++++++++++++++++++ templates/base.html | 3 +- 5 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 templates/API.html diff --git a/pages.go b/pages.go index de00351..d3a2249 100644 --- a/pages.go +++ b/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) diff --git a/server.go b/server.go index b707909..427186a 100644 --- a/server.go +++ b/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) diff --git a/templates.go b/templates.go index 78c7215..0473505 100644 --- a/templates.go +++ b/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", diff --git a/templates/API.html b/templates/API.html new file mode 100644 index 0000000..c4225e1 --- /dev/null +++ b/templates/API.html @@ -0,0 +1,93 @@ +{% extends "base.html" %} + +{% block head %} + +{% endblock %} + +{% block content %} +
+
+
+ +

API

+ +

Uploading a file

+ +

To upload a file, make a PUT request to {{ siteurl }}upload/ and you will get the url of your upload back.

+ +

Optional headers with the request

+ +

Randomize the filename
+ Linx-Randomize: yes

+ +

Specify a custom deletion key
+ Linx-Delete-Key: mysecret

+ +

Specify an expiration time (in seconds)
+ Linx-Expiry: 60

+ +

Get a json response
+ Accept: application/json

+ +

The json response will then contain:

+ +
+

“url”: the publicly available upload url
+ “filename”: the (optionally generated) filename
+ “delete_key”: the (optionally generated) deletion key,
+ “expiry”: the unix timestamp at which the file will expire (0 if never)
+ “size”: the size in bytes of the file
+ “mimetype”: the guessed mimetype of the file
+ “sha256sum”: the sha256sum of the file,

+
+ +

Examples

+ +

Uploading myphoto.jpg

+ + 
$ curl -T myphoto.jpg {{ siteurl }}upload/  
+{{ siteurl }}myphoto.jpg
+ +

Uploading myphoto.jpg with an expiry of 20 minutes

+ + 
$ curl -H "Linx-Expiry: 1200" -T myphoto.jpg {{ siteurl }}upload/
+{{ siteurl }}myphoto.jpg
+ +

Uploading myphoto.jpg with a random filename and getting a json response:

+ + 
$ curl -H "Accept: application/json" -H "Linx-Randomize: yes" -T myphoto.jpg {{ siteurl }}/upload/  
+{"delete_key":"...","expiry":"0","filename":"f34h4iu.jpg","mimetype":"image/jpeg",
+"sha256sum":"...","size":"...","url":"{{ steurl }}/f34h4iu.jpg"}
+ +

Deleting a file

+ +

To delete a file you uploaded, make a DELETE request to {{ siteurl }}yourfile.ext with the delete key set as the Linx-Delete-Key header.

+ +

Example

+ +

To delete myphoto.jpg

+ + 
$ curl -H "Linx-Delete-Key: mysecret" -X DELETE {{ siteurl }}myphoto.jpg
+DELETED
+ +

Information about a file

+ +

To retrieve information about a file, make a GET request the public url with Accept: application/json headers and you will receive a json response containing:

+ +
+

“url”: the publicly available upload url
+ “filename”: the (optionally generated) filename
+ “expiry”: the unix timestamp at which the file will expire (0 if never)
+ “size”: the size in bytes of the file
+ “mimetype”: the guessed mimetype of the file
+ “sha256sum”: the sha256sum of the file,

+
+ +

Example

+ + 
$ curl -H "Accept: application/json" {{ siteurl }}/myphoto.jpg
+{"expiry":"0","filename":"myphoto.jpg","mimetype":"image/jpeg","sha256sum":"...","size":"..."}
+
+
+
+{% endblock %} diff --git a/templates/base.html b/templates/base.html index 8187c5a..e62f35f 100644 --- a/templates/base.html +++ b/templates/base.html @@ -14,7 +14,8 @@