Skip to content
This repository has been archived by the owner on Apr 25, 2022. It is now read-only.

Programmstruktur

Jump to bottom
KIMB-technologies edited this page Mar 11, 2018 · 12 revisions

Server API

Es gibt zwei Typen der API eine AJAX API, welche mit Sessions arbeitet und eine RESTful API, welche den Authentifikationscode aus Authentifikationslinks nutzt.

Die URL für einen Request ist wie folgt aufgebaut:

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

https://notes.example.com/rest.php?auth
https://notes.example.com/ajax.php?login

Jeder Task bestimmt weitere (POST-)Parameter, bei denen auch die Reihenfolge definiert ist. Die meisten Tasks (inkl. Parameter) sind für REST und AJAX gleich.

Task ajax.php rest.php Beschreibung
login ✔ ✘ Session erstellen (User einloggen), User ausloggen, Status abfragen
auth ✘ ✔ Authcode erstellen, UserID bestimmen
list ✔ ✔ Liste lesen und bearbeiten, Notizarchiv
view ✔ ✔ Datei lesen und schreiben, Verlauf, Freigaben bearbeiten
admin ✔ ✔ User hinzufügen und löschen
account ✔ ✔ Authcode erstellen und löschen, Passwort ändern
share ✔ ✘ Inhalt der Freigaben lesen und schreiben (RESTful, trotzdem ajax.php)

Bei Anfragen an die REST API muss immer die UserID (userid) und ein Authcode (authcode) mittels POST angegeben werden (Ausnahmen in auth).
Bei Anfragen an die AJAX API müssen Cookies korrekt behandelt werden und weiterhin hat die Session eine Lebensdauer.

Anfragen

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.

Antwort

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.

Task login

  • 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

Task auth

  • 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)
  }

Task list

  • 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)
  	"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

Task view

Task admin

Task account

Task share

WebApp

Die WebApp ist in JavaScript geschrieben und besteht grob gesagt aus drei Teilen.

  1. Login
    • Freigaben erkennen
    • Authentifikationslinks und Sessions erkennen
    • REST oder AJAX API wählen
    • Login mit Loginformular durchführen
    • Logout Button anzeigen und mit Leben füllen
  2. Notizliste
    • Liste der Notizen
    • Neue Notizen erstellen
  3. Notes
    • Notizen lesen und schreiben
    • Freigabe
    • Verlauf

Weiterhin gibt es:

  • Account-Manager
    • Passwort ändern
    • Authentifikationslinks verwalten
  • Admin-Dialog
    • User erstellen und löschen
  • Notizarchiv
    • Erlaubt es gelöscht (archivierte) Notizen wiederzuholen.
  • Freigaben
    • Präsentiert dem User die Freigaben
  • Offline-Manager
    • Speichert die Offline-Änderungen an Notizen und lädt sie sobald wie möglich hoch.

Globale Funktionen und Variablen

  • Globale Variablen Allgemein (sowas wie allgemeine API)
    • JSON : userinformation = { "name": String, "id": String, "admin" : bool , "authcode" : String }
      • allgemeine Userdaten werden hier verfügbar gehalten
      • wird im localStorage gesichert
    • bool : systemOfflineMode
      • true, wenn die WebApp offline ist
      • wird von der ajax_request-Funktion gesetzt
    • OfflineManager : systemOfflineManager
      • eine Instanz des OfflineManagers
    • bool : systemRESTAPI
      • true, wenn die WebApp REST API nutzt
      • wird von Login gesetzt und von ajax_request beachtet
  • Globale Funktionen Allgemein (sowas wie allgemeine API)
    • void review( enabled )
      • einen der drei Bereich im DOM anzeigen, die anderen ausblenden
      • enabled : (login, noteview, noteslist, globalloader)
    • void errorMessage( message, remove )
      • global eine Fehlermeldung anzeigen
      • Text der Medlung String, null für keine Meldung
      • (optional, Standard 10) int Zeit in Sekunden bis Meldung verschwindet, false um immer anzuzeigen
    • void ajax_request( task, post, callback, errcallback )
    • function confirmDialog(cont, buttons, title)
  • Globale Variablen von Funktionen (sowas wie public Attribute und Methoden)
    • int : errorMessageTimeOut
    • bool : list_first_load
    • CodeMirror : cm_editor
    • function : newerNoteOnServerFound
  • localStorage Daten
    • ToDo

Ablauf des Programms und seiner Teile

Beim Aufruf der Seite wird zuerst der erste Teil Login gestartet.

Login

Teil Login geht wie folgt vor (bei Nein/ nicht erfolgreich zum nächsten Punkt, bei Ja/ erfolgreich zum Unterpunkt):

  1. Prüfe ob Freigabelink geöffnet
    • rufe Freigaben auf
  2. Prüfe auf Logindaten im localStorage
    • Authcode vorhanden
      • nutze REST API für Notizliste
    • Andernfalls prüfe Session
      • nutze AJAX API für Notizliste
  3. Prüfe ob ein Authentifikationslink aufgerufen
    • Teste den Link am Server
      • nutze REST API für Notizliste
  4. Zeige Loginformular
    • Bitte User um Eingabe seiner Daten
    • Versuche mit Daten einzuloggen
      • nutze AJAX API für Notizliste

Vor dem Aufruf der Notizliste wird der Logoutbutton und die Buttons für Account-Manager und evtl. Admin-Dialog angezeigt.
Außerdem wir eine regelmäßige Prüfung der Session gestartet, diese erkennt auch Änderungen an geöffnete Notizen auf dem Server.

Der Logoutbutton zerstört die Session auf dem Server (wenn AJAX API) und löscht entweder den gesamten localStorage oder nur die User-Informationen. Außerdem werden die DOM-Elemente bereinigt.

Notizliste

Notes

Account-Manager

Admin-Dialog

Notizarchiv

Freigaben

Offline-Manager

Desktop-Application

Allgemein erfragt die App Servername und die Logindaten und erstellt mit diesen einen Authentifikationslink. Anschließend wird über ein WebView Element KIMB-Notes geladen, wobei der Authentifikationslink übergeben wird.

ToDo

← Zurück zu Home
© KIMB-technologies

Clone this wiki locally