API draft added

2014-01-04 21:44:22 +01:00
parent 5292a96d78
commit 90a93e8aff
1 changed files with 133 additions and 0 deletions
@@ -0,0 +1,133 @@
+# NoteHub API
+
+**Version 1.0, status: draft!**
+
+## Prerequisites
+
+The NoteHub API can only be used in combination with a __Publisher ID__ (PID) and __Publisher Secret Key__ (PSK), which can be issued [here](http://notehub.org/api/register). The PSK can be revoked at any moment in case of an API abuse.
+
+A PID is a string is chosen by the publisher and cannot be longer than 16 characters (e.g.: __notepadPlugin__). A PSK will be generated by the NoteHub API and is a string of hex characters of length 32. (e.g.: ...)
+
+All API requests must be issued with one special parameter `version` denoting the expected version of the API as  a string, e.g. `"1.0"` (see examples below).
+
+## Note Retrieval
+
+A simple `GET` request to the following URL:
+
+    http://notehub.org/api/get-note?v=1.0&title=<NOTE-ID>
+
+will return a JSON object containing following self explaining fields: `noteID`, `note`, `longURL`, `shortURL`, `statistics`, `status`.
+
+Example:
+
+    {
+        note: <markdown source>,
+        longURL: "http://notehub.org/2014/1/3/lorem-ipsum",
+        shortURL: "http://notehub.org/0vrcp",
+        statistics: {
+            published: "2014-1-3",
+            views: 24
+        },
+        status: {
+            success: true,
+            comment: <some server message>
+        }
+    }
+
+Hence, the status of the request can be evaluated by reading of the property `status.success`. The field `status.comment`might contain an error message, a warning or some comments from the server.
+
+The note ID is a string, containing the date of publishing and a few first words of the note (usually the header), e.g.: `"2014/1/3/lorem-ipsum"`.
+
+## Note Creation
+
+A note must be created by a `POST` request to the following URL:
+
+    http://notehub.org/api/v1.0/post-note
+
+Together with the following parameters:
+
+Parameter    | Explanation                              | Type
+---          | ---                                      | ---
+`note`       | Text to publish                          | **required**
+`pid`        | Publisher ID                             | **required**
+`signature`  | Signature                                | **required**
+`password`   | MD5 hash of a plain password for editing | *optional*
+`version`    | Used API version                         | **required**
+
+The Signature must be computed on the client side using the note text _and_ the PSK, wrt. the algorithm described below. The signature serves as a proof, that the request is authentic and the will be issued by the publisher corresponding to the provided PID.
+
+The response of the server will contain the fields `noteID`, `longURL`, `shortURL`, `status`.
+
+Example:
+
+    {
+        noteID: "2014/1/3/lorem-ipsum",
+        longURL: "http://notehub.org/2014/1/3/lorem-ipsum",
+        shortURL: "http://notehub.org/0vrcp",
+        status: {
+            success: true,
+            comment: <some server message>
+        }
+    }
+
+The status object serves the same purpose as in the case of note retrieval.
+
+## Note Update
+
+To update a note, an `UPDATE` request must be issued to the following URL:
+
+    http://notehub.org/api/v1.0/update-note
+
+with the following parameters:
+
+Parameter    | Explanation                                       | Type
+---          | ---                                               | ---
+`noteID`     | Note-ID                                           | **required**
+`note`       | New text                                          | **required**
+`pid`        | Publisher ID                                      | **required**
+`signature`  | Signature                                         | **required**
+`password`   | MD5 hash of the plain password used for creation  | **required**
+`version`    | Used API version                                  | **required**
+
+The Signature is computed identically to the note creation.
+
+The response of the server will contain the fields `longURL`, `shortURL`, `status`.
+
+Example:
+
+    {
+        longURL: "http://notehub.org/2014/1/3/lorem-ipsum",
+        shortURL: "http://notehub.org/0vrcp",
+        status: {
+            success: true,
+            comment: <some server message>
+        }
+    }
+
+The status object serves the same purpose as in the case of note retrieval and creation.
+
+## Signature Implementation
+
+The signature is computed as a very simple hash function. Consider the following sample implementation in JavaScript:
+
+    function getSignature(text, psk) {
+        var hash = 5381;
+        for (var pos = 0; pos < text.length; pos++){
+            hash = ((hash << 5) + hash) + 
+                   (text.charCodeAt(pos) ^ psk.charCodeAt(hash % psk.length));
+        }
+        return hash;
+    }
+
+Note:
+ - the `hash` variable is typed as a signed 32-bit integer
+ - `^`denotes an XOR
+ - `charCodeAt()` returns the char code of the note letter at the given position; e.g., it will return values [97, 167, 1092] for three characters of the string `"a§ф"`.
+
+Your can test your implementation on the following tests:
+
+Input                                                   | Output
+---                                                     | ---
+"Lorem ipsum dolor sit amet", "abcdef"                  | 3577853521
+"Notehub is a free pastebin for markdown", "12345678"   | -180217198
+"Short note", "A VERY LONG KEY"                         | -1135299015