notehub/API.md

NoteHub API

Version 1.3, status: released.

Changelog

• V1.3: New note ID format.
• V1.2: Theme & fonts can be specified during the publishing.
• V1.1: fields publisher and title in the response to the note retrieval.
• V1.0: initial release.

Prerequisites

The NoteHub API can only be used in combination with a Publisher ID (PID) and Publisher Secret Key (PSK), which can be requested here. The PSK can be revoked at any moment in case of an API abuse.

A PID is a string chosen by the publisher and cannot be longer than 16 characters (e.g.: notepadPlugin). A PSK will be generated by the NoteHub API and can be a string of any length and content.

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). You should always put the version of this document as a version parameter.

NoteHub API Access Request

To register as a publisher and gain access to NoteHub API, please [send](mailto:notehub@icloud.com?subject=NoteHub API Access Request&body=Please add [a] desired PID as a 16 char string [b] your contact information, [c] short usage explanation and [d] the URL of the resource or it's website.) an email with the following information about you: the desired PID, your contact information, a short description of what you want to do and an URL of the resource where the API will be used or its website.

Note Retrieval

A simple GET request to the following URL:

http://notehub.org/api/note

with the following parameters:

Parameter	Explanation	Type
noteID	Note-ID	required
version	Used API version	required

will return a JSON object containing following self explaining fields: note, title, longURL, shortURL, statistics, status, publisher.

Example:

{
    note: "markdown source",
    title: "Lorem Ipsum.",
    longURL: "http://notehub.org/2014/1/3/lorem-ipsum",
    shortURL: "http://notehub.org/0vrcp",
    statistics: {
        published: "2014-1-3",
        edited: "2014-1-12",
        views: 24
    },
    status: {
        success: true,
        comment: "some server message"
    },
    publisher: "Publisher Description"
}

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 any other 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 title), e.g.: "2014/1/3/lorem-ipsum". This ID will be generated by NoteHub automatically.

Note Publishing

A note must be created by a POST request to the following URL:

http://notehub.org/api/note

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
theme	Theme name	optional
text-font	Text font name	optional
header-font	Header font name	optional

The Signature is the MD5 hash of the following string concatenation:

pid + psk + note

The signature serves as a proof, that the request is authentic and will be issued by the publisher corresponding to the provided PID.

The parameters specifying the theme name and fonts are optional and only impact the URLs returned back.

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 PUT request must be issued to the following URL:

http://notehub.org/api/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 publishing	required
version	Used API version	required

The Signature is the MD5 hash of the following string concatenation:

pid + psk + noteID + note + password

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