From 6f38e13fb87d4d7a3244f99b174116fdd8929529 Mon Sep 17 00:00:00 2001
From: El RIDO <elrido@gmx.net>
Date: Sun, 18 Oct 2015 16:52:02 +0200
Subject: [PATCH] Updated API (markdown)

---
 API.md | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/API.md b/API.md
index 4cc75aa..7d3dcbc 100644
--- a/API.md
+++ b/API.md
@@ -1,18 +1,41 @@
-ZeroBin uses AJAX requests for certain operations. While not yet fully developed into a standards compliant REST or JSON-RPC, it is documented here for reference.
+ZeroBin uses AJAX requests for certain operations.
+
+## As of Version 0.22
+
+All JSON-API requests need to be sent with the HTTP header `X-Requested-With: JSONHttpRequest`. The query strings below would be appended after the `?` in the URL, i.e. query string `foo` on the site URL of `https://example.com/zerobin/` would become `https://example.com/zerobin/?foo`.
+
+ Action                           | Type | Query String | Data to send | Result ([JSON-LD](http://json-ld.org/)) 
+----------------------------------|------|--------------|--------------|-------------------
+retrieve paste (and its comments) | GET  | `[pasteID]`  | (no data) | [paste.jsonld](https://raw.githubusercontent.com/elrido/ZeroBin/master/js/paste.jsonld)
+create paste                      | PUT  | `[pasteID]` | `data=[cipherdata]&expire=[expireID]& formatter=[formatID]&burnafterreading=[1/0]& opendiscussion=[1/0]` | [paste.jsonld](https://raw.githubusercontent.com/elrido/ZeroBin/master/js/paste.jsonld) (including deletetoken)
+create paste                      | POST | (empty query string) | `data=[cipherdata]&expire=[expireID]& formatter=[formatID]&burnafterreading=[1/0]& opendiscussion=[1/0]` | [paste.jsonld](https://raw.githubusercontent.com/elrido/ZeroBin/master/js/paste.jsonld) (including deletetoken)
+create comment                    | PUT  | `[commentID]` | `data=[cipherdata]&parentid=[parentID]& pasteid=[pasteID]&nickname=[cipherdata]` | `{"status":0, "id":"[commentID]"}`
+create comment                    |d POST | (empty query string) | `data=[cipherdata]&parentid=[parentID]& pasteid=[pasteID]&nickname=[cipherdata]` | `{"status":0, "id":"[commentID]"}`
+delete paste (burn after reading) | DELETE  | (empty query string) | `pasteid=[pasteID]&deletetoken=burnafterreading` | `{"status":0, "id":"[pasteID]"}`
+delete paste (burn after reading) | POST  | (empty query string) | `pasteid=[pasteID]&deletetoken=burnafterreading` | `{"status":0, "id":"[pasteID]"}`
+delete paste                      | DELETE  | (empty query string) | `pasteid=[pasteID]&deletetoken=[deletetoken]` | `{"status":0, "id":"[pasteID]"}`
+delete paste                      | POST  | (empty query string) | `pasteid=[pasteID]&deletetoken=[deletetoken]` | `{"status":0, "id":"[pasteID]"}`
+Error on any of the above           | N/A | N/A | N/A | `{"status":1, "message":"[errormessage]"}`
+
+## Until Version 0.21.1
 
 The query strings below would be appended after the `?` in the URL, i.e. query string `foo` on the site URL of `https://example.com/zerobin/` would become `https://example.com/zerobin/?foo`.
 
  Action                             | Type | Query String | Data to send (JSON) | Result (JSON) 
 ------------------------------------|------|--------------|---------------------|--------------
-retrieve paste (and its comments) | GET  | `[pasteID]&json` | (no data) | `{"status":0, "id":"[pasteID]"}`
+retrieve paste (and its comments) | GET  | `[pasteID]&json` | (no data) | `{"status":0, "id":"[pasteID]", "messages": [array of one paste and its comments if any]}`
 create paste                      | POST | (empty query string) | `{"data":"[cipherdata]", "expire":"[expireID]", "burnafterreading":[1/0], "opendiscussion":[1/0]}` | `{"status":0, "id":"[pasteID]", "deletetoken":[token]}`
 create comment                    | POST | (empty query string) | `{"data":"[cipherdata]", "parentid":"[parentID]", "pasteid":[pasteID], "nickname":[cipherdata]}` | `{"status":0, "id":"[pasteID]"}`
 delete paste (only for burn after reading pastes) | GET  | `pasteid=[pasteID]&deletetoken=burnafterreading` | (no data) | `{"status":0, "id":"[pasteID]"}`
 Error on any of the above           | N/A | N/A | N/A | `{"status":1, "message":"[errormessage]"}`
 
-### Legend
+## Legend
 
 * **pasteID:** ID of the paste, 16 characters long, hexadecimal
 * **parentID:** ID of the comments parent (paste ID or comment ID), 16 characters long, hexadecimal
-* **cipherdata:** binary data, output of the encryption function
-* **expireID:** expiration key as defined in the [configuration file](https://github.com/elrido/ZeroBin/blob/master/cfg/conf.ini#L50) of the service
\ No newline at end of file
+* **commentID:** ID of the comment, 16 characters long, hexadecimal
+* **cipherdata:** JSON string containing format and base64 encoded data, output of the encryption function
+* **expireID:** expiration key as defined in the [configuration file](https://github.com/elrido/ZeroBin/blob/master/cfg/conf.ini#L56) of the service
+* **formatID:** format key as defined in the [configuration file](https://github.com/elrido/ZeroBin/blob/master/cfg/conf.ini#L69) of the service
+* **metadata:** various properties of the [paste](https://raw.githubusercontent.com/elrido/ZeroBin/master/js/pastemeta.jsonld) or the [comment](https://raw.githubusercontent.com/elrido/ZeroBin/master/js/commentmeta.jsonld).
+* **deletetoken:** the delete token is returned only on creation of a paste and can be used to delete it and its comments
\ No newline at end of file