crappyrules/notehub
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

API removed

Browse Source
This commit is contained in:
Christian Müller
2015-09-26 00:51:57 +02:00
parent 5e0af56938
commit 4ba2601798
2 changed files with 0 additions and 268 deletions
Download Patch File Download Diff File Expand all files Collapse all files
API.deprecated.md
-147
View File
@@ -1,147 +0,0 @@
# NoteHub API
**Version 1.4, status: released.**
## Changelog
- **V1.4**: Bugfix: no whitespace elimination from the note text is required now for the signature computation.
- **V1.3**: New note ID format.
- **V1.2**: Theme & font settings 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](#registration). 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.
Once you obtained your PSK, you can test the API [here](/api-test.html).
## <a name="registration"></a>NoteHub API Access Request
To register as a publisher and gain access to NoteHub API, please <a href="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.">send</a> 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:
https://www.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: "https://www.notehub.org/2014/1/3/lorem-ipsum",
shortURL: "https://www.notehub.org/0vrcp",
statistics: {
published: "1396250865735",
edited: "1412516289863",
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.comment`might 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:
https://www.notehub.org/api/note
with the following parameters:
Parameter | Explanation | Type
--- | --- | ---
`note` | Text to publish | **required**
`pid` | Publisher ID | **required**
`signature` | Signature | **required**
`password` | Secret token (plain or hashed) | *optional*
`version` | Used API version | **required**
`theme` | Theme name | *optional*
`text-size` | Text size | *optional*
`header-size`| Header size | *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. Please note, that _all_ of the values used in the signature computation, should be identical to the values passed with the request itself.
Ensure, that your note contains only `\n` symbols as line breaks!
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: "https://www.notehub.org/2014/1/3/lorem-ipsum",
shortURL: "https://www.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:
https://www.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` | Secret token (plain or hashed) | **required**
`version` | Used API version | **required**
The Signature is the MD5 hash of the following string concatenation:
pid + psk + noteID + note + password
Please note, that all of the values used in the signature computation, should be identical to the values passed with the request itself.
Ensure, that your note contains only `\n` symbols as line breaks!
The response of the server will contain the fields `longURL`, `shortURL`, `status`.
Example:
{
longURL: "https://www.notehub.org/2014/1/3/lorem-ipsum",
shortURL: "https://www.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.
resources/public/api-test.html
-121
View File
@@ -1,121 +0,0 @@
<!DOCTYPE html>
<html>
<head>
<link href="//maxcdn.bootstrapcdn.com/bootstrap/2.3.2/css/bootstrap.min.css" rel="stylesheet">
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<title>NoteHub API Testing</title>
<meta charset="UTF-8">
</head>
<body>
<script>
function request(type, data) {
$("#request").text(JSON.stringify(data));
$.ajax({
type: type,
dataType: 'json',
url: "/api/note",
data: data,
success: function(result){
$("#response").text(JSON.stringify(result));
}
});
}
function selectForm(name) {
["#get", "#post", "#update"].forEach(function(elem){
if(name==elem) {
$(elem + "-form").show();
$(elem + "-li").addClass("active");
} else {
$(elem + "-form").hide()
$(elem + "-li").removeClass("active");
}
});
}
function getNote(){
var data = {
noteID: $("#get-noteID").val(),
version: $("#version").val()
};
request("GET", data);
}
function postNote(){
var data = {
note: $("#post-note").val(),
pid: $("#pid").val(),
signature: $("#post-signature").val(),
password: $("#post-password").val(),
version: $("#version").val()
};
request("POST", data);
}
function updateNote(){
var data = {
noteID: $("#update-noteID").val(),
note: $("#update-note").val(),
pid: $("#pid").val(),
signature: $("#update-signature").val(),
password: $("#update-password").val(),
version: $("#version").val()
};
request("PUT", data);
}
</script>
<div class="container">
<div class="page-header">
<h1>NoteHub API Testing</h1>
</div>
<label>PID</label>
<input id="pid" type="text">
<label>PSK</label>
<input id="psk" type="text">
<label>API version</label>
<input id="version" type="text" value="1.4">
<br/>
<ul class="nav nav-tabs">
<li id="get-li" class="active"><a href="javascript:selectForm('#get')">Get Note</a></li>
<li id="post-li"><a href="javascript:selectForm('#post')">Post Note</a></li>
<li id="update-li"><a href="javascript:selectForm('#update')">Update Note</a></li>
</ul>
<form id="get-form">
<fieldset>
<label>noteID</label>
<input id="get-noteID" type="text" value="2014/1/3/lorem-ipsum">
<br/>
<a href="javascript:getNote()" class="btn">Submit</a>
</fieldset>
</form>
<form id="post-form" style="display: none;">
<fieldset>
<label>note</label>
<textarea id="post-note"></textarea>
<label>signature (md5 hash of pid + psk + note)</label>
<input id="post-signature" type="text" value="">
<label>password</label>
<input id="post-password" type="text" value="">
<br/>
<a href="javascript:postNote()" class="btn">Submit</a>
</fieldset>
</form>
<form id="update-form" style="display: none;">
<fieldset>
<label>noteID</label>
<input id="update-noteID" type="text" value="">
<label>note</label>
<textarea id="update-note"></textarea>
<label>password</label>
<input id="update-password" type="text" value="">
<label>signature (md5 of pid + psk + noteID + note + password)</label>
<input id="update-signature" type="text" value="">
<br/>
<a href="javascript:updateNote()" class="btn">Submit</a>
</fieldset>
</form>
<h4>Request</h4>
<pre id="request" class="prettyprint linenums">
</pre>
<h4>Response</h4>
<pre id="response" class="prettyprint linenums">
</pre>
</div>
</body>
</html>