Documentation: API

Anthony Grimes edited this page May 29, 2014 · 25 revisions
Clone this wiki locally

Introduction

RefHeap has a simple API. The API is token-based, though some methods don't require authentication for certain tasks. To get an API token, create an account on RefHeap and go to the API page. You can view/generate API tokens there.

All of the API methods return JSON. The API tries to return useful status codes. The status codes that can possibly be returned are 422, 404, 201, 204, 400, and 200.

All API methods except for fetching single pastes can take the following parameters:

  • username
  • token

All POSTed parameters are generally expected to be form urlencoded in the body. Refheap will not accept multipart form data. All params can be passed as query arguments, but I wouldn't rely on that forever.

Furthermore, all API methods that return structured data can return either JSON or Clojure data structures as responses. The default is JSON. To make the API return Clojure, pass along the return parameter and set it to "clojure". The response will be application/clojure.

The base URL of the API is https://www.refheap.com/api. All non-https traffic is redirected to https and all traffic to refheap.com is redirected to the www subdomain.

If you write a library for the API in any language, please add it to the list.

Methods

POST /paste

  • private: Optional. Either "true" or "false". Defaults to "false".
  • language: Optional. A string of which language to use for the paste or a file extension. If this is not provided or the language is unrecognizable, the API defaults to "Plain Text". If a language name is passed, it must be exactly the same as how it is listed in the dropdown on RefHeap. If the language is "Nginx Configuration" then that is exactly how it must appear when passed to the API. If a file extension is passed, it must begin with a dot (e.g. ".clj"). Keep in mind that not all of the things that RefHeap can highlight have an associated file extension. Also, there are a lot of file extensions, so if there is one missing for a given lexer, please open an issue about it so I can add/fix it.
  • contents: Required. A string of text that will be the body of the paste. This cannot be empty.

Create a new paste.

If a username and token is provided then the paste will be associated with that account. Otherwise, it will be anonymous.

Here is an example using Clojure and clj-http:

user=> (clj-http.client/post "https://www.refheap.com/api/paste"
                             {:form-params {:contents "i like foo" :username "Raynes"
                                            :token "000000-00000-000-0000000-0000"
                                            :private true
                                            :language "IRC Logs"}})

{:status 200,
 :cookies
 {"ring-session"
  {:path "/",
   :version 0,
   :discard true,
   :value "69f1008e-4c04-4366-880f-7a868a48f5f6"}},
 :headers
 {"server" "Jetty(6.1.25)",
  "content-type" "application/json; charset=ISO-8859-1",
  "date" "Thu, 05 Jan 2012 04:18:03 GMT",
  "connection" "close"},
 :body "{\"lines\":1,\"date\":\"2012-01-05T04:18:03.473Z\",\"paste-id\":\"4f05247bd6c4d4f67f6cd123\",\"language\":\"Plain Text\",\"private\":true,\"url\":\"https://www.refheap.com/paste/4f05247bd6c4d4f67f6cd123\",\"user\":\"raynes\",\"contents\":\"i like foo\"}"}

GET /paste/:id

  • id: Required. The id of the paste you want to fetch.

Fetch a paste.

Example using Clojure and clj-http:

user=> (clj-http.client/get "https://www.refheap.com/api/paste/52")

{:cookies
 {"ring-session"
  {:discard true,
   :path "/",
   :value "a0949bbd-665f-4add-86ca-25f3f69eda4a",
   :version 0}},
 :status 200,
 :headers
 {"date" "Thu, 05 Jan 2012 20:00:02 GMT",
  "content-type" "application/json; charset=ISO-8859-1",
  "connection" "close",
  "server" "Jetty(6.1.25)"},
 :body
 "{\"lines\":1,\"date\":\"2012-01-05T04:14:56.995Z\",\"paste-id\":\"52\",\"language\":\"Plain Text\",\"private\":false,\"url\":\"https://www.refheap.com/paste/52\",\"user\":null,\"contents\":\"i like foo\"}"}

POST /paste/id

Parameters are the same as for creating pastes except that, if any given parameter is not provided, the default is what was in the old paste.

Edit pastes.

You have to be authenticated in order to edit a paste.

Example using Clojure and clj-http:

user=> (clj-http.client/post "https://www.refheap.com/api/paste/4f05fb90d6c4670e22a5cce2" 
                             {:form-params {:username "Raynes" 
                                            :token "000000-00000-000-0000000-0000" 
                                            :contents "(+ 5 5)" 
                                            :language "Clojure" 
                                            :private false}})

{:status 200,
 :cookies
 {"ring-session"
  {:path "/",
   :version 0,
   :discard true,
   :value "998c3de2-638e-4b73-92fd-848cbeb9bd89"}},
 :headers
 {"server" "Jetty(6.1.25)",
  "content-type" "application/json; charset=ISO-8859-1",
  "date" "Thu, 05 Jan 2012 19:42:37 GMT",
  "connection" "close"},
 :body "{\"lines\":1,\"date\":\"2012-01-05T19:35:43.126Z\",\"paste-id\":\"59\",\"language\":\"Clojure\",\"private\":false,\"url\":\"https://www.refheap.com/paste/59\",\"user\":\"raynes\",\"contents\":\"(+ 5 5)\"}"}

DELETE /paste/:id

  • id: Required. The paste id.

Delete a paste. You must be the owner of the paste in order to delete it.

Example using Clojure and clj-http:

user=> (clj-http.client/delete "https://www.refheap.com/api/paste/59" 
                               {:query-params {:username "Raynes" 
                                               :token "000000-00000-000-0000000-0000"}})

{:status 204, :cookies {"ring-session"
  {:path "/",
   :version 0,
   :discard true,
   :value "e3e5e6bc-9ddd-4b14-9a06-4bc08a70ff09"}},
 :headers
 {"server" "Jetty(6.1.25)",
  "date" "Thu, 05 Jan 2012 19:43:52 GMT",
  "connection" "close"},
 :body nil}

POST /paste/:id/fork

  • id: Required. Id of the paste you want to fork.

Fork a paste to an account. You pass a username and token.

Example using Clojure and clj-http:

user=> (clj-http.client/post "https://www.refheap.com/api/paste/44/fork"
                             {:form-params {:username "Raynes"
                                            :token "35155a3f-4db3-4495-9934-7a24b9c4eed8"}})

{:cookies
 {"ring-session"
  {:discard true,
   :path "/",
   :value "20aea8a6-2ec9-4b4d-b253-ed1a958681ea",
   :version 0}},
 :status 201,
 :headers
 {"server" "nginx/0.7.65",
  "date" "Sat, 07 Jan 2012 07:28:15 GMT",
  "content-type" "application/json; charset=ISO-8859-1",
  "connection" "close"},
 :body
 "{\"lines\":11,\"date\":\"2012-01-07T07:28:14.974Z\",\"paste-id\":\"50\",\"fork\":\"44\",\"language\":\"Plain Text\",\"private\":false,\"url\":\"https://www.refheap.com/paste/50\",\"user\":\"raynes\",\"contents\":\"[clojure.set/union clojure.set/intersection clojure.set/difference\\nclojure.core/long clojure.core/short clojure.core/+ clojure.core/*\\nclojure.core/unchecked-long clojure.core/+' clojure.core/unchecked-short\\nclojure.core/unchecked-int clojure.core/macroexpand-1\\nclojure.core/hash clojure.core/comp clojure.core/byte\\nclojure.core/rationalize clojure.core/macroexpand clojure.core/*'\\nclojure.core/max clojure.core/identity clojure.core/biginteger\\nclojure.core/force clojure.core/int clojure.core/bigint\\nclojure.core/num clojure.core/disj clojure.core/unchecked-byte\\nclojure.core/dissoc clojure.core/merge clojure.core/min\\nclojure.core/disj!]\"}"}

GET /paste/:id/highlight

Get the raw HTML of a paste (from pygments) with no theme information.

This example is Haskell with the http-conduit library (because I had a Haskell REPL open but not a Clojure one.)

repl> simpleHttp "https://www.refheap.com/api/paste/1/highlight"
Chunk "{\"content\":\"<table class=\\\"highlighttable\\\"><tr><td class=\\\"linenos\\\"><div class=\\\"linenodiv\\\"><pre><a href=\\\"#L-1\\\">1</a></pre></div></td><td class=\\\"code\\\"><div class=\\\"highlight\\\"><pre><a name=\\\"L-1\\\"></a><span class=\\\"p\\\">(</span><span class=\\\"nf\\\">begin</span><span class=\\\"p\\\">)</span>\\n</pre></div>\\n</td></tr></table>\"}" Empty