Sie zeigen eine alte Version dieser Seite an. Zeigen Sie die aktuelle Version an.

Unterschiede anzeigen Seitenhistorie anzeigen

« Vorherige Version anzeigen Version 42 Nächste Version anzeigen »

Der Service befindet sich im Entwicklungsstadium. D.h. es wird sich noch einiges ändern, insbesondere die Struktur der Daten.

Einführung:

Ab Nuclos 4.0 hat der Nuclos Server einen RESTful Service integriert, der automatisch gestartet wird. Er dient primär als Interface für einen Webclient, kann aber auch grundsätzlich als Dienst verwendet werden.

Er ist unter dem Pfad "/rest/*" zu erreichen, z.B. für eine lokale Installation des Servers auf dem Port 8080:

http://localhost:8080/nuclos-war/rest/<pfad>.  (z.B. für logout: http://localhost:8080/nuclos-war/rest/logout)

Session:

Jeder Teilservice außer dem Login benötigt eine Session ID. Wird keine Session ID übergeben, bzw. ist die Session ID ungültig, gibt der Service einen Fehler mit dem HTTP Status 401 (Unauthorized) zurück. Die Session ID kann entweder als Standard-Cookie oder als Http-Header-Parameter beim Aufruf des REST-Services übergeben werden. Der Key muss "sessionid" lauten.

Zu Debug-Zwecken ist vorläufig auch die Möglichkeit gegeben, die Session ID als Query-Parameter zu übergeben. Als Beispiel würde dies hier bei gültiger Session ID funktionieren: http://localhost:8080/nuclos-war/rest/meta/entities?sessionid=i8F3KD12V9c13SqDsvcT

Teilservices/Pfade:

  • Login (Path: /login, Method: POST, Return: String)
    Erwartet die Login-Daten per JSON (s. JSON-Spezifikationen), authentifiziert sich damit am Nuclos-Server und gibt eine SessionID als String zurück. Die Session ID benötig wird um alle anderen Teilservices zu verwenden. Schlägt der Login fehl, wird ein Fehler mit dem HTTP Status 401 (Unauthorized) zurückgeworfen.

  • Logout (Path: /logout, Method: GET)
    Invalidiert die bestehende Session ID. Diese Methode gibt den HTTP Status 200 (OK), wenn die Session ID gültig war.

  • Entities (Path: /meta/entities, Method: GET, Return: JSON-Array "Entity")
    Liefert alle Entitäten zurück, auf die der Benutzer lesend zugreifen kann.

  • Fields (Path: /meta/fields/{uid}, Method: GET, Return: JSON-Array "Field")
    Gibt die Felder und die Metadaten der Entität {uid} zurück.

  • LoadData (Path: /data/load/{uid}, Methods: GET/POST, Return: JSONObject "Result")
    Mit GET werden die ersten 1000 Datensätze der Entität {uid} geladen. Mit POST kann ein Filter (s. JSON-Spezifikationen) übergeben werden.

  • GetData (Path:/data/get/{uid}/{pk}, Method: GET, Return: Return: JSONObject "Result")
    Es wird der Datensatz der Entität {uid} mit dem Primärschlüssel {pk} zurückgegeben, falls er existiert.

  • Search (Path: /data/search/{text}, Method: GET, Return: JSON-Array "SearchResult")
    Durchsucht die Entitäten nach dem Suchtext {text} mit Hilfe des Lucene-Indexes.

  • Count (Path: /data/count/{uid}, Method: GET/POST, Return: Number)
    Zählt die Anzahl der Datensätze der Entität {uid}. Mit POST kann ein Filter (s. JSON-Spezifikationen) übergeben werden.

  • Update (Path: /data/update, Method: PUT, Return: JSONObject "ValueObject")
    Erwartet ein JSONObject "ValueObject" von einem existierenden Datensatz. Auf diesen wird ein UPDATE mit den übergebenen Werten ausgeführt. Falls kein Fehler auftritt, wird der Datensatz direkt aus der Datenbank nach dem UPDATE zurückgegeben.

  • Insert (Path: /data/insert, Method: POST, Return: JSONObject "ValueObject")
    Erwartet ein JSONObject "ValueObject" von einem neuem Datensatz. Dieser wird mit INSERT in die Datenbank geschrieben. Falls kein Fehler auftritt, wird der Datensatz direkt aus der Datenbank nach dem INSERT zurückgegeben.

  • Delete (Path: /data/delete/{uid}/{pk}, Method: DELETE)
    Löscht einen Datensatz mit dem Primary Key {pk} aus der Entität {uid}. Sobald der Datensatz ordnungsgemäß entfernt wurde, wird ein HTTP Status 200 (OK) zurückgegeben.

JSON-Spezifikationen:

  • Login ("username": String, "password": String, "locale": String (optional))
    Beispiel für ein gültiges Login-JSONObject:

    var login = {
	"username": "user123", 
	"password": "passXYZ", 
	"locale": "de_DE"};

  • Filter ("search": String, "offset": Number, "chunksize": Number, "sort": String, alle optional)
    Beispiel für ein gültiges Filter-JSONObject:

    var filter = {
	"search": "Hu", 
	"offset": 0, 
	"chunksize": 100, 
	"sort": "szU1s75TFT6kGF7l0Whj=asc"};

  • ValueObject ("uid": String, "pk": String, "<FieldUID>": Object, beliebige Anzahl)
    Beispiel für ein gültiges ValueObject-JSONObject:

    var vo = {
	"uid":"KIb7Pmxm3AnJtdBWXWsJ",
 	"pk":"40000191",
 	"nyVRqlqCUYvH3GNwlKrn":400,
 	"zTc3H0vtH5o2JV82gRtg":"Schraube"}

     

     

     

  • Entity ("uid": String, "statemodel": Boolean, "name": String)
    Beispiel für ein Entity-JSONObject:

    {"uid":"KIb7Pmxm3AnJtdBWXWsJ",
 "statemodel":false,
 "name":"Artikel"}

  • Field ("uid": String, "name": String, "type": String, "readonly": Boolean, order: Array[Integer])
    Beispiel für ein Field-JSONObject:

    {"uid":"KIb7Pmxm3AnJtdBWXWsJ",
 "name":"Bestand",
 "type":"Integer",
 "readonly":false,
 "order",[3]}

  • Result ("total": Number, "vos": JSONArray von ValueObjects)
    "total" ist die Anzahl alle Datensätze, die die Suche ohne Einschränkung der Blockgröße gefunden hat. Beispiel für ein Result-JSONObject:

    {"total":4,"vos":[
{"uid":"KIb7Pmxm3AnJtdBWXWsJ","nyVRqlqCUYvH3GNwlKrn":400,"zTc3H0vtH5o2JV82gRtg":"Schraube","pk":"40000191"},  {"uid":"KIb7Pmxm3AnJtdBWXWsJ","nyVRqlqCUYvH3GNwlKrn":41,"zTc3H0vtH5o2JV82gRtg":"Stuhl","pk":"40000192"}]}

  • SearchResult ("uid": String, "name": String, "pk": String, "text": String)
    Beispiel für ein SearchResult-JSONObject:

    {"uid":"KIb7Pmxm3AnJtdBWXWsJ",
 "name":"Artikel"
 "pk":"40000217"
 "text":"anzahl=4, lieferung=2013-06-28, lieferbar=null, name=Schrank, preis=256.17"}

HTTP-Statuscodes:

  • 200 OK
    Wird von Services ohne Return-Object (z.b. Login oder Delete) zurückgegeben, wenn die Aktion erfolgreich durchgeführt worden ist.

  • 401 Unauthorized
    Ohne oder mit ungültiger Session ID wird dieser Status gemeldet. Bei fehlgeschlagenem Login ebenfalls.

  • 403 Forbidden
    Wird eine Aktion versucht, zu der der User keine Berichtigung besitzt (z.b. Ändern einer Entität, auf der nur Leseberechtigung besteht), kommt diese Meldung.

  • 404 Not Found
    Wenn der Pfad des Services nicht korrekt ist, wird 404 zurückgegeben.

  • 406 Not Acceptable
    Bei Fehlern in den JSON-Objekten (bei POST und PUT) erscheint diese Meldung.

  • 430 Custom "CommonFatalException"
    Bei der Verarbeitung von Daten wurde eine "CommonFatalException" geworfen.


 

  • Keine Stichwörter