RESTful Service

Bitte beachten Sie, dass sich der RESTful Service noch in Entwicklung befindet und noch keine Aufwärtskompatibilität sichergestellt wird. Insbesondere können sich Servicenamen und Aufrufparameter noch ändern.

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 bis auf wenige Ausnahmen (z.B. 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/menu?sessionid=i8F3KD12V9c13SqDsvcT

Teilservices/Pfade:

Version (Path: /version, Method: GET, Return: String, ohne Session)
Version des Nuclos-Servers.
Login (Path: /login, Method: POST, Return: String, ohne Session)
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 andere 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.

Menu (Path: /meta/menu, Method: GET, Return: JSONArray "Menu")
Das Menü in der Sprache des angemeldet Benutzers. Hinweis: Momentan werden nur Menüeinträge für Businessobjekte bis zum Level 1 bereitgestellt.
Tasks (Path: /meta/tasks, Method: GET, Return: JSONArray "Menu")
Das Menü bestehend aus Tasks (Suchfilter) in der Sprache des angemeldet Benutzers.
EntityMeta (Path: /meta/entity/{uid}, Method: GET, Return: JSONObject "EntityMeta")
Liefert die Metadaten des Businessobjekt {uid} mit ihren Feldern zurück.
SearchFilter (Path: /meta/searchfilter/{uid}, Method: GET, Return: JSONObject "EntityMeta")
Liefert die Metadaten des zum Suchfilter {uid} zugeordneten Businessobjekt mit ihren Feldern zurück.
PreviewData (Path: /data/preview/{uid}, Methods: POST, Return: JSONObject "PreviewResult")
Lädt eine Vorschau der Daten zu einem Businessobjekt {uid}. Mit POST wird ein Filter für die Daten (s. JSON-Spezifikationen) übergeben.
SubLoad (Path: /data/subload/{uid}/{field}/{fk}, Method: GET, Return: JSONObject "Result")
Lädt die Unterformulardaten eines Sub-Businessobjekts mit dem Fremdschlüssel {fk} im Feld {field}. Die Master-Entität ist {uid}.
GetData (Path:/data/get/{uid}/{pk}, Method: GET, Return: JSONObject "Result", Optional Path:/data/get/{uid}/{pk}/{uchash})
Es wird der Datensatz des Businessobjekts {uid} mit dem Primärschlüssel {pk} zurückgegeben, falls er existiert. Optional kann mit {uchash} ein Hashwert, welcher mit dem letzt-gelesenen Datensatz geliefert worden ist, mitgegeben wird. Bei Übereinstimmung der Hashwerte werden keine neue Metadaten über Felder und Unterformulare geliefert.

SubGetData (Path:/data/subget/{uid}/{subform}/{pk}, Method: GET, Return: JSONObject "Result")
Es wird der Datensatz des Unterformulars {subform} mit dem Primärschlüssel {pk} zum Hauptformular des Businessobjekts {uid} zurückgegeben, falls er existiert.
GetInfo (Path:/data/getinfo/{uid}, Method: POST, Return: JSONObject "Result")
Die Preview Daten "_title" und "_info" zu einem Unterformular-Datensatz, der mit Post übergeben wird, werden erzeugt. {uid} ist das Businessobjekt des Hauptformulars
ReferenceList (Path: /data/referencelist/{uid}/{field}, Method: GET, Return: JSON-Array "ReferenceValue")
Erstellt eine Liste von Reference-Werten zum Feld {field} des Businessobjekts {uid}. Die Liste ist momentan auf maximal 1000 Einträge beschränkt. Der Parameter {uid} ist ab Nuclos 4 obsolet und wird nicht mehr verwendet. Die Syntax des Pfades wird bald angepasst.
Search (Path: /data/search/{text}, Method: GET, Return: JSON-Array "SearchResult")
Durchsucht das Businessobjekt nach dem Suchtext {text} mit Hilfe des Lucene-Indexes.
Delete (Path: /data/delete/{uid}/{pk}, Method: DELETE)
Löscht einen Datensatz mit dem Primärschlüssel {pk} aus dem Businessobjekt {uid}. Sobald der Datensatz ordnungsgemäß entfernt wurde, wird ein HTTP Status 200 (OK) zurückgegeben.
InsertUpdate (Path: /data/insertupdate, Method: POST, Return: JSONObject "ValueObject")
Erwartet ein JSONObject "ValueObject" von einem neuem oder alten Datensatz. Dieser wird mit je nach flag mit INSERT in die Datenbank geschrieben oder mit UPDATE verändert. Falls kein Fehler auftritt, wird der Datensatz direkt aus der Datenbank nach der Operation zurückgegeben.
Mit dem Feld "_newstate" kann ein Statuswechsel ausgeführt werden.
SubOpen (Path: /data/subopen/{uid}/{subform}/{pk}/{file}, Method: GET, Return APPLICATION_OCTET_STREAM
Liefert den Dateianhang aus einem Dokumentenunterformular {subform} zurück. {file} Bezeichnes den Namen, unter dem der Anhang gespeichert wird.

Ab Nuclos 4.1 implementiert:

FieldGet (Path: /data/fieldget/{field}|{pk}, Method: GET, Return JSONObject "Result"
VLPData (Path: /data/vlpdata/{field}, Method: POST, Return JSON-Array "ValueId")
SubLoadWithParameters(Path: /data/subload/{uid}/{field}/{fk}, Method: POST, Return: JSONObject "Result")
ReferenceList (Path: /data/referencelist/{field}, Method: GET, Return: JSON-Array "ReferenceValue")
ActionService (Path: /action/button/{uid}, Method: POST, Return JSON-Array "ValueObject")

Hinweis: Die {uid} des Businessobjektes kann bei einigen Methoden alternativ auch die {uid} eines Feldes des Businessobjektes sein, da durch das Feld das Businessobjekt eindeutig identifiziert ist. Dies gilt für GetData, PreviewData, GetInfo, Delete, SubGetData und SubOpen.

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, "searchfilter", String, optional)
Beispiel für ein gültiges Filter-JSONObject:
```
var filter = {
	"search": "Hu", 
	"offset": 0, 
	"chunksize": 100, 
	"sort": "desc:szU1s75TFT6kGF7l0Whj",
	"searchfilter": "9XRAkACDWgJulpAiYCHs"};
```
-

ValueObject to Server ("_uid": String, "_pk": Number/String, "_flag": "insert/update/delete", "<FieldUID>": Object, beliebige Anzahl, "_newstate": StatusUID für neuen Status, optional, "_subvos": Array aus ValueObjects, optional)
Beispiel für ein gültiges ValueObject-JSONObject:

var vo = {
	"_uid":"KIb7Pmxm3AnJtdBWXWsJ",
 	"_pk":40000191,
	"_flag":"update",
 	"nyVRqlqCUYvH3GNwlKrn":400,
 	"zTc3H0vtH5o2JV82gRtg":"Schraube",
    "_newstate":"hj8wS2lLCi6Rs57E",
	"_subvos":[{"_uid":"KIb7Pmxm3AnJtdBWXWsJ","zTc3H0vtH5o2JV82gRtg":"Schraube","_pk":40000191,"_flag":"update"},
               {"_uid":"KIb7Pmxm3AnJtdBWXWsJ","zTc3H0vtH5o2JV82gRtg":"Stuhl","_pk":40000192,"flag":"delete"}]}

-

ValueObject from Server ("_uid": String, "_pk": Number/String, "<FieldUID>": Object, beliebige Anzahl, "_readonly": Boolean, "_uchash": Number, optional, "_states": Array aus States, optional, .....)
Beispiel für ein ValueObject-JSONObject:

var vo = {
	"_uid":"KIb7Pmxm3AnJtdBWXWsJ",
 	"_pk":40000191,
 	"nyVRqlqCUYvH3GNwlKrn":400,
 	"zTc3H0vtH5o2JV82gRtg":"Schraube",
	"_readonly":false,
	"_uchash":687445,
	"_states":[{"pk":"opJ0ga7T6rEnl9F3","name":"Zugewiesen","numeral":10,"current":true},
			   {"pk":"opJ0ga7T6rEnl9F2","name":"In Arbeit","numeral":20,"current":false}],
	"_canopen":false,
	"_tabs":[],
	"_fields":[],
^	"_title":"Element A10",
	"_info":"Neuer Datensatz..., 245, frei",
	"_image":"iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAGXRFWHRTb2Z"}

-

EntityMeta ("uid": String, "statemodel": Boolean, "name": String, "statemodel": Boolean, "readonly": Boolean, "nodelete": Boolean, "fields": Array aus Fields, "hasImage": Boolean, "searchfilter": String, nur für Service Searchfilter )
Beispiel für ein EntityMeta-JSONObject:

{"uid":"KIb7Pmxm3AnJtdBWXWsJ",
 "name":"Artikel",
 "statemodel":false,
 "readonly":false,
 "nodelete":false,
 "fields":[{"uid":"cjJ9ga7T6rEnl9FNMNrMdy2","name":"Name","type":"String",
           "readonly":false,"unique":true,"nullable":false,"reference":false,"order":0},
          {"uid":"wwS2lLCi6Rs57E","name":"Bestand","type":"Number",
           "readonly":false,"unique":false,"nullable":true,"reference":false,"order":1}]
 "hasImage":true,
 "searchfilter":"9XRAkACDWgJulpAiYCHs"}

-

Field ("uid": String, "name": String, "type": String, "readonly": Boolean, "unique": Boolean, "nullable": Boolean, "reference": Boolean, "order": Number)
Beispiel für ein Field-JSONObject:
```
{"uid":"KIb7Pmxm3AnJtdBWXWsJ",
 "name":"Bestand",
 "type":"Number",
 "readonly":false,
 "unique":false,
 "nullable":true,
 "reference":false,
 "order",3}
```
-

(Preview)Result ("total": Number, "title": String, "vos": Array aus 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,"title":"Artikel","vos":[
{"uid":"KIb7Pmxm3AnJtdBWXWsJ","nyVRqlqCUYvH3GNwlKrn":400,"zTc3H0vtH5o2JV82gRtg":"Schraube","pk":40000191},  {"uid":"KIb7Pmxm3AnJtdBWXWsJ","nyVRqlqCUYvH3GNwlKrn":41,"zTc3H0vtH5o2JV82gRtg":"Stuhl","pk":40000192}]}

-

SearchResult ("uid": String, "name": String, "pk": Number/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"}

-

ReferenceValue ("pk": Number/String, "name": String)
Beispiel für ein ReferenceValue-JSONObject:
```
{"pk":40006894,
 "name":"Herr Rossi"}
```
-
SubEntity ("name": String, "Entity": String, "field": String)
Beispiel für ein SubEntity-JSONObject:
```
{"name":"Artikel,
 "Entity":"KIb7Pmxm3AnJtdBWXWsJ",
 "field":"szU1s75TFT6kGF7l0Whj"}
```
-
State ("pk": Number/String, "name": String, "numeral": Number, "current": Boolean, "icon": Base64-Image, optional)
Beispiel für ein State-JSONObject:
```
{"pk":40000717,
 "name":"Zugewiesen",
 "numeral":10,
 "current":true}
```
-

Menu ("path": String, "entries": Array("uid": String, "name": String, "icon": Base64-Image, optional))
Beispiel für ein Menu-JSONObject:

{"path":"Freetime",
 "entries":[{"uid":"oJeMHK7Y9A-1L7fOVrocA","name":"Ladder"},
            {"uid":"k4lF4lDOcA-nl36NMw","name":"TreeHouse","icon":"iVBORw0KGgoAAAANSUhEUgA"},
            {"uid":"Uzmz50InTg-yJ21HtZIA","name":"New Entity","icon":"iVBORw0KGgoAAAANSUhEUgA"}]}

Datentypen:

Um die 4 JSON-Datentypen (String, Number, Boolean, Null) weiter zu definieren, kann der Datentyp explizit in von den MetaDaten ermittelt werden, z.B. durch den Service "Field". Folgende Datentypen werden u.a. geliefert.

String
Number (bedeutet hier ganzzahlige Nummer)
Decimal (bedeutet hier exakte Dezimalzahl, vgl. mit java-BigDecimal)
Boolean
Date (als JSON-String)
weitere NuclosSpezifische Typen, werden als (JSON-String) geliefert.

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 eines Businessobjekts, 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.

Seitenhierarchie

RESTful Service