Alle Anfragen werden als POST-Request an die dem Task und Server entsprechende URL gestellt.

https://<<notes-url>>/[rest/ajax].php?<<task>>

Im Folgenden sind die Parameter für ajax.php und rest.php gleich, falls die Parameter authcode und userid nicht aufgeführt sind, müssen sie bei REST Anfragen hinzugefügt werden.

Der Server antwortet immer mit einem JSON Objekt, welches mittels PHP erstellt wurde. Der HTTP-Status-Code wird von KIMB-Notes nicht verändert, er zeigt nur Serverfehler und Fehlkonfigurationen an.

Aufbau des Objekts:

{
	"error" : [], // Array mit Fehlermeldungen, bei "status" : "okay" leer 
	"status" : "...", // entweder "error" oder "okay"
	"data" : ... // Daten je nach Anfrage
}

Im folgenden werden nur die Daten in "data" angegeben.

• User einloggen (mittels Session/ Cookie)

    {
    	"username" : Username als String [a-z]
    	"password" : Hex des SHA 256 Hashes des Passworts [a-z0-9]
    }
  

  Antwort:

    {
    	"id" : UserID des Users als String [a-z]^(30)
    	"admin" : Adminrechte vorhanden? [boolean]
    }
  

• Status des Users abfragen (Session noch gültig)

    {
    	"status" : UserID des zu prüfenden Users [a-z]^(30)
    }
  

  Antwort:

    Session noch gültig [boolean]
  

• Users ausloggen (Session löschen/ Cookie erneuern)

    {
    	"logout" : null
    }
  

  Antwort:

    [] leeres Array
  

• UserID aus Name und Authcode bestimmen

    {
    	"username" : Username als String [a-z]
    	"authcode" : Authcode des Users [a-z0-9]
    }
  

  Antwort:

    {
    	"id" : UserID des Users als String [a-z]^(30)
    	"admin" : Adminrechte vorhanden? [boolean]
    }
  

• Mittels Username und Passwort einen Authcode anfordern

    {
    	"username" : Username als String [a-z]
    	"password" : Hex des SHA 256 Hashes des Passworts [a-z0-9]
    	(optional) "authcode" : leerer String, ohne Bedeutung
    }
  

  Antwort:

    {
    	"name" : Username als String [a-z]
    	"id" : UserID des Users als String [a-z]^(30)
    	"admin" : Adminrechte vorhanden? [boolean]
    	"authcode" : neuer Authcode für den Account [a-z0-9]^(75)
    }
  

• Notizliste anzeigen

    {
    	"userid" : UserID als String
    }
  

  Antwort: sortiertes Array aus user/user_*.json (siehe Datenstruktur)

• Notizliste bearbeiten (hoch, runter, archivieren)

    {
    	"userid" : UserID als String
    	"art" : Auswahl der Möglichkeiten ("del" löschen, "up" nach oben bewegen, "down" nach unten bewegen, "star" hervorgehoben invertieren)
    	"noteid" : NoteID der zu verschiebenden/ löschenden Notiz [a-f0-9]^(100)
    }
  

  Antwort

    [
    	Erfolgreich [boolean],
    	Meldung über durchgeführte Änderung
    ]
  

• Neue Notiz hinzufügen

    {
    	"userid" : UserID als String
    	"name" : Name der neuen Notiz [a-z0-9A-Z]
    }
  

  Antwort

    {
    	"id" : NoteID der neuen Notiz [a-f0-9]^(100)
    }
  

• Archiv aufrufen und daraus wiederherstellen

    {
    	"userid" : UserID als String
    	"reload" : NoteID der wiederherzustellenden Notiz oder "none" um Liste zu zeigen [a-z0-9]
    }
  

  Antwort bei "reload" : "none": Array von allen Notizen des Users im Archiv

    [
    	{
    		"noteid" : NoteID der Notiz im Archiv
    		"name" : Name der Notiz
    		"geaendert" : Zeitpunkt der letzten Änderung String [H:i:s d.m.Y]
    	}, 
    	...
    ]
  

  Antwort sonst: leeres Array

• Notiz lesen/ Verlauf lesen/ Zeitpunkt der letzten Änderung lesen

    {
    	"userid" : UserID als String
    	"noteid" : NoteID der zu lesenden Notiz
    	"history" : Auswahl zwischen 2 (einfach lesen), 3 (3 Verlauf), 4 (letzte Änderung) [integer]
    }
  

  Antwort bei einer leeren Notiz

    {
    	"empty" : true (Notiz leer? [boolean])
    	"geandert" : Zeitpunkt der letzten Änderung (jetzt) [unix timestamp]
    }
  

  Antwort bei "history" : 2

    {
    	"name" : Name der Notiz
    	"id" : NoteID der Notiz
    	"content" : Inhalt der Notiz, markdown
    	"geandert" : Zeitpunkt der letzten Änderung [unix timestamp]
    	"empty" : Notiz leer? [boolean]
    }
  

  Antwort bei "history" : 3: Array mit den verschiedenen Versionen (aktuellste oben)

    [
    	{
    		"diff" : Diff zwischen den Versionen, html
    		"time" : Zeitpunkt der Version String [H:i:s d.m.Y]
    		"text" : Notiz in der Version, markdown
    	},
    	...
    ]
  

  Antwort bei "history" : 4

    Zeitpunkt der letzten Änderung [unix timestamp]
  

• Notiz schreiben

    {
    	userid : UserID als String
    	noteid : NoteID der zu schreibenden Notiz
    	note : {
    		name : Name der Notiz
    		cont : Inhalt der Notiz, markdown
    	}
    }
  

  Eine Version im Verlauf wird angelegt, falls die letzte Änderung mehr als 10 Minuten her ist oder der alte und der neue Inhalt weniger als 80 % Ähnlichkeit aufweisen.

  Der Name der Notiz ist hier änderbar, er wird aber nur in der Notiz, nicht in der Notizliste geändert.

  Antwort

    [
    	erfolgreich? [boolean],
    	"Aenderung" oder "Keine Aenderung",
    	Meldung zum Verlauf (bei Änderung),
    	Zeitpunkt der letzten Änderung (jetzt) [unix timestamp]
    ]
  

  Die Übergabe der Zeitpunkte der letzten Änderung sind dazu da, Änderungen auf einem anderen Gerät erkennen zu können.

  Um Ungenauigkeiten zu verhindern wir immer die Serverzeit genommen, auch wenn man sie lokal bestimmen könnte.

• Freigaben verwalten

  Geht nicht für leere Notizen!

    {
    	'userid' : UserID
    	'noteid' : NoteID der zu schreibenden Notiz
    	(optional) 'share' : { // löschen oder erstellen
    		'authcode' : Code der Freigabe (nicht Authcode des Users!) [A-Za-z0-9]^(75)
    			// authcode == leer um neu zu erstellen, andernfalls zu löschende Freigabe 
    		'edit' : Bearbeiten der neuen Freigabe erlauben? [boolean]
    		'name' : Name für die neue Freigabe
    	}
    }
  

  Antwort ohne "share": Array über alle Freigaben

    [
    	{
    		"authcode": Code der Freigabe [A-Za-z0-9]^(75)
    		"edit": Bearbeiten erlaubt? [boolean]
    		"lastAccessed": Zeitpunkt des letzten Aufrufs als String [H:i:s d.m.Y]
    		"accesses": Anzahl der Aufrufe [integer]
    		"created": Zeitpunkt der Erstellung als String [H:i:s d.m.Y]
    		"name": Name der Freigabe
    	},
    	...
    ]
  

  Antwort "share""authcode" : "leer": neue Freigabe erstellen

    String "added"
  

  Antwort sonst: Freigabe löschen

    String "done"
  

Zugriff nur möglich für User die Adminrechte haben.

• Liste der User anzeigen

    {
    	"userid" : UserID des zugreifenden Admins
    	"art" : "list"
    }
  

  Antwort

    {
    	"list" : [
    		{
    			"username" : Username des Users [a-z]
    			"userid" : UserID des Users [a-z]^(30)
    			"admin" : Hat User Adminrechte? [boolean]
    		},
    		... // Array über alle User
    	],
    	"salt" : Salt für ein neues Passwort [A-Za-z0-9]^(40)
    }
  

• User hinzufügen

    {
    	"userid" : UserID des zugreifenden Admins
    	"art" : "add",
    	"user" : {
    		"name" : Username des neuen Users (darf nicht vergegeben sein) [a-z]
    		"admin" : Soll neuer User Adminrechte bekommen? [boolean]
    		"password" : Passworthash in HEX des neuen Users [sha256(sha256(<pass>) '+' <salt>)]
    		"salt" : Salt, welches für Passworthash genutzt wurde
    	}
    }
  

  Antwort

    {
    	"done": Erfolgreich erstellt? [boolean]
    }
  

• User löschen

    {
    	"userid" : UserID des zugreifenden Admins
    	"art" : "del",
    	"deluserid" : UserID des zu löschenden Users
    }
  

  Antwort

    {
    	"done": Erfolgreich gelöscht? [boolean]
    }
  

  Es wird nur der Account, nicht aber die Notizen des Users gelöscht!

• Salt erstellen

    {
    	"userid" : UserID	
    }
  

  Antwort

    Salt für ein neues Passwort [A-Za-z0-9]^(40)
  

• Passwort ändern

    {
    	"userid" : UserID	
    	"newpass" : Passworthash in HEX des neuen Users [sha256(sha256(<pass>) '+' <salt>)]
    	"salt" : Salt, welches für Passworthash genutzt wurde
    }
  

  Antwort

    true // wenn Änderung erfolgreich
  

• Authcodes auflisten/ erstellen/ löschen

    {
    	"userid" : UserID	
    	"art" :  Auswahl der Möglichkeiten ( "list" Codes auflisten, "new" Neuen Code erstellen, "del" Code löschen)
    	"id" : ID des Codes beim Löschen oder nicht-leerer String
    }
  

  Antwort "art" : "list": false wenn keine Codes vorhanden, andernfalls Array über alle Codes

    [
    	{
    		"time" : Zeitpunkt der letzten Nutzung als String [d.m.Y H:i:s]
    		"code" : die ersten zehn Stellen des Codes
    		"id" : ID des Code (SHA256 Hash des Codes in HEX)
    	},
    	...
    ]
  

  Antwort "art" : "new": der vollständige neue Authcode [a-z0-9]^(75)

  Hier ist die einzige Stituation in der der Server den vollen Code ausgibt, wenn er nicht gespeichert wird, dann ist der Code weg und er muss gelöscht und ein neuer erstellt werden.

  Antwort "art" : "del" (es wird der Code erlöscht, dessen Hash in id angegeben wird)

    true // wenn löschen erfolgreich
  

• Freigabe öffnen

    {
    	"authcode" : Authcode der Freigabe, nicht des Users
    }
  

  Antwort

    {
    	"name" : Name der freigegeben Notiz
    	"id" => NoteID der freigegeben Notiz
    	"content" => Inhalt der freigegebenen Notiz, markdown
    	"geandert" => Zeitpunklt der letzten Änderung [unix timestamp]
    	"edit" => Bearbeitung der Freigabe erlaubt? [boolean]
    }
  

• Freigabe ändern (sofern bearbeiten erlaubt)

    {
    	"authcode" : Authcode der Freigabe, nicht des Users
    	"cont" : neuer Inhalt der Freigabe, markdown
    }
  

  Antwort

    [
    	erfolgreich? [boolean],
    	"Aenderung" oder "Keine Aenderung",
    	Meldung zum Verlauf (bei Änderung),
    	Zeitpunkt der letzten Änderung (jetzt) [unix timestamp]
    ]
  

  Schreiben des Verlaufs wie bei Task view.