Table of content

General

How to use the API

To access the API you have to send a get-request with the accordingly required key/value "action". In case authentication is necessary you have to send also the user credentials as post-request (in the same request). For more information read readme-license.txt.

Example:

http://example.com/api.php?key=value

How to authenticate

These are the post parameters which you should send, when a command needs authetication. You must not send the credentials in plaintext. For a successful authentication take 5 times the md5 hash of the username and the password and send these.

Example:

$pass = "Foobar";
for($i = 0; $i < 5; ++$i) {
$pass = md5($pass);
}

Post Parameter

KeyValue
adminUsernameusername
adminPasswordpassword

Commands

Authenticate

Example:

http://example.com/api.php?action=auth

Get Parameter

Key Value Required Needs Authentication
action"auth"

Response

If credentials were right the response is "All Right". If not it is "Error: Unauthorized.".

Get Comments

Example:

http://example.com/api.php?action=getDB

Get Parameter

Key Value Required Needs Authentication
action"getDB"ᐨᐨ
showMails"TRUE"ᐨᐨ

Response

By default this will return all comments as a JSON array but with all mail adresses md5-hashed and all IP addresses md5-hashed twice.
If showMails is set to TRUE mail and IP addresses will send clearly.

Save A New Comment

Example:

http://example.com/api.php?action=save&id=E73BF175-F920-447D-993D-CE4169F17BCD

Get Parameter

Key Value Required Needs Authentication
action"save"ᐨᐨ

Post Parameter

Key Value Required Needs Authentication
id"E73BF175-F920-447D-993D-CE4169F17BCD"
(by default)
(by default)ᐨᐨ
commentatorNamecommentator's nameᐨᐨ
commentatorEmailcommentator's emailᐨᐨ
commentatorTextcommentator's commentᐨᐨ
commentatorWebsitecommentator's websiteᐨᐨᐨᐨ

Further Information

The id is the value of the hidden input tag (look at example.html#tmpID) which should be something random like an uuid.
Except for the id, the required values should be checked with JavaScript because they are not checked by the API.

Response

If the id is missing the API will return "Error: Unauthorized.". If the comment could be saved the API returns the comment's JSON value. If there was an error saving the comment the API will return "Error: Comment could not be saved.".

Remove Comment

Example:

http://example.com/api.php?action=remove&id=4b28fa38834c5c

Get Parameter

Key Value Required Needs Authentication
action"remove"
idcomment's id
(without "id_")

Response

If id is empty or not sent it will be returned "Error: No ID sent or it is empty.". If the comment's deletion was successful it will be returned the deleted comment's id.

Object Classes

Comments

Instance Variables

  • $items

    Array with all comments

Methods

  • addComment(comment)

    Adds comment (an instance of the Comment object) to $items.
    Returns nothing (void).

  • allComments(databasefilename)

    Opens databasefilename, reads the JSON content (should be an array) and assigns it to $items.
    Returns nothing (void).

Comment

Instance Variables

  • $name

    The commentator's name. (String)

  • $email

    The commentator's email. (String)

  • $text

    The comment itself. (String)

  • $creationDate

    The creation date is an unix timestamp
    in milliseconds. (Number)

  • $url

    The commentator's website. (String)

  • $id

    The comment's (unique) id. (String)

  • $IP

    The commentator's IP. (String)

Methods

  • createComment(name, email, text, url, ip)

    Assigns the passed value (name, email, text, url, ip) to the object (an instance of the Comment object).
    Returns nothing (void).