notehub/API.md

# 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