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. 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.commentmight 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