Differences

This shows you the differences between two versions of the page.

--- de:jvx:common:util:rest [2018/02/08 08:30]
admin created
+++ de:jvx:common:util:rest [2020/07/24 23:47]
admin
@@ Line 1: / Line 1: @@
-~~Title: REST Service~~
+~~Title: REST Dienste~~
-Wir definieren die Business Logik mit [[de:jvx:server:lco:objects|Life-Cycle Objekten]] am Server. Die Zugriffsberechtigung einer Applikation wird durch einen [[de:jvx:server:security:manager|Security Manager]]geprüft. Der Zugriff auf die Business Logik erfolgt üblicherweise via Master- oder SubConnections vom Client.
+Wir definieren die Business Logik mit [[de:jvx:server:lco:objects|Life-Cycle Objekten]] am Server. Die Zugriffsberechtigung einer Applikation wird durch einen [[de:jvx:server:security:manager|Security Manager]] geprüft. Der Zugriff auf die Business Logik erfolgt üblicherweise via Master- oder SubConnections vom Client.
 Um die Technologie Unabhängigkeit zu vollenden, steht die Komplette Business Logik einer Applikation auch via REST zur Verfügung.
-Für die Benützung der REST Services ist die Autentifizierung mit Benutzername und Passwort notwendig. Als Authentifizierungsmechanismus wird [[https://de.wikipedia.org/wiki/HTTP-Authentifizierung#Basic_Authentication|BASIC]] erwendet Die Überprüfung der Daten wird vom Security Manager der Applikation wie gewohnt durchgeführt. Sie müssen für die Integration der REST Services keine Zeile Source Code verändern.
+Für die Benützung der REST Dienste ist die Autentifizierung mit Benutzername und Passwort notwendig. Als Authentifizierungsmechanismus wird [[https://de.wikipedia.org/wiki/HTTP-Authentifizierung#Basic_Authentication|BASIC]] erwendet Die Überprüfung der Daten wird vom Security Manager der Applikation wie gewohnt durchgeführt. Sie müssen für die Integration der REST Dienste keine Zeile Source Code verändern.
 =====Funktionsweise=====
-Die REST Implementierung in JVx wurde mit [[http://www.restlet.org/|Restlet]] umgesetzt. Um die REST Services zu nutzen, muss der Deployment Deskriptor wie folgt konfiguriert werden:
+Die REST Implementierung in JVx wurde mit [[http://www.restlet.org/|Restlet]] umgesetzt. Um die REST Dienste zu nutzen, muss der Deployment Deskriptor wie folgt konfiguriert werden:
 <file xml>
@@ Line 30: / Line 30: @@
 Mit dieser Konfiguration stehen folgende Services zur Verfügung:
-===== Available services =====
+===== Verfügbare Dienste =====
-====Storage Zugriff  (CRUD, Meta Data)====
+==== Administration ====
+Für die Administration stehen unterschiedliche Dienste zur Verfügung. Diese können im Standardfall nur mittels POST Requests verwendet werden. Falls jedoch benutzerdefinierte Dienste registriert wurden, können diese auch mittels GET Request angesprochen werden.
+Folgende Dienste stehen standardmässig zur Verfügung:
+  * [[#anmeldung_testen|Anmeldung testen]]
+  * [[#passwort_aendern|Passwort ändern]]
+  * [[#datenbank_pruefen|Datenbank prüfen]]
+=== Anmeldung testen ===
+Test URL:\\
+''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/_admin/**<fc #BF0000>testAuthentication</fc>**'' \\
+oder \\
+''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/_admin/**<fc #BF0000>testAuthentication</fc>**/**<fc #BF0000>parameter</fc>**''
+Der Request benötigt eine HashMap im JSON Format.
+Beispiel:
+<file json>
+{ "username" : "admin",
+  "password" : "adminpassword"
+}
+</file>
+Der Benutzername kann auch weggelassen werden. In diesem Fall wird dann der Parameter aus dem URL als Benutzername verwendet.
+== POST-Response ==
+Wenn die Anmeldung erfolgreich war, wird kein Response generiert und der Status Code ist 204 (SUCCESS_NO_CONTENT).
+=== Passwort ändern ===
+Test URL:\\
+''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/_admin/**<fc #BF0000>changePassword</fc>**'' \\
+oder \\
+''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/_admin/**<fc #BF0000>changePassword</fc>**/**<fc #BF0000>parameter</fc>**''
+Der Request benötigt eine HashMap im JSON Format.
+Beispiel:
+<file json>
+{ "username" : "admin",
+  "oldpassword" : "oldpassword",
+  "newpassword" : "newpassword"
+}
+</file>
+Der Benutzername kann auch weggelassen werden. In diesem Fall wird dann der Parameter aus dem URL als Benutzername verwendet.
+== POST-Response ==
+Wenn das Passwort geändert wurde, wird kein Response generiert und der Status Code ist 204 (SUCCESS_NO_CONTENT).
+=== Datenbank prüfen ===
+Test URL:\\
+''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/_admin/**<fc #BF0000>checkDB</fc>**''
+== GET-Response ==
+Wenn die Prüfung erfolgreich war, wird kein Response generiert und der Status Code ist 204 (SUCCESS_NO_CONTENT). Wenn die Datenbank nicht verfügbar ist, wird der Status Code 500 (SERVER_ERROR_INTERNAL) geliefert. Es ist ebenfalls möglich das die Konfiguration nicht gefunden werden konnte. In diesem Fall wird der Status Code 503 (SERVER_ERROR_SERVICE_UNAVAILABLE) geliefert.
+=== Benutzerdefinierte Dienste ===
+Wenn man einen eigenen Dienst zur Laufzeit registrieren möchte, kann dies mittels
+<code java>
+AdminService.register(String pApplicationName, String pAction, IAdminServiceDelegate pDelegate);
+AdminService.unregister(String pApplicationName, String pAction, Class<? extends IAdminServiceDelegate> pClass)
+</code>
+erfolgen. Der Dienst kann entweder per GET oder POST Request angesprochen werden, je nachdem ob **//IAdminServiceGetDelegate//** oder **//IAdminServicePostDelegate//** verwendet wird.
+Der Aufruf erfolgt mittels:
+''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/_admin/**<fc #BF0000>ACTION</fc>**'' \\
+oder \\
+''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/_admin/**<fc #BF0000>ACTION</fc>**/**<fc #BF0000>parameter</fc>**''
+==== Storage Zugriff  (CRUD, Meta Data) ====
   * [[#get-request_select|Select]]
@@ Line 85: / Line 168: @@
 ==POST-Request (Insert)==
-Insert a new record:
+Einen neuen Datensatz einfügen:
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/data/**<fc #BF0000>STORAGE_NAME</fc>**''
-The request requires a HashMap in JSON format. The column name is used as the key.
+Der Request benötigt eine HashMap im JSON Format. Als Key wird die Spaltenbezeichnung verwendet.
-Example:
+Beispiel:
 <file json>
@@ Line 101: / Line 184: @@
 == POST-Response ==
-The response returns the complete record in JSON format:
+Der Response liefert den vollständigen Datensatz im JSON Format:
 <file json>
@@ Line 117: / Line 200: @@
 == PUT-Request (Update) ==
-Update a requord with Primary Key:
+Einen Datensatz per PK aktualisieren:
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/data/**<fc #BF0000>STORAGE_NAME</fc>**/**<fc #BF0000>PRIMARY_KEY</fc>**''
-If the PK is composed of several columns or if the records are not to be identified via the PK, the query parameters must be used:
+Wenn der PK aus mehreren Spalten zusammengesetzt ist oder der Datensatze nicht über den PK identifiziert werden sollen, müssen die Query Parameter verwendet werden:
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/data/**<fc #BF0000>STORAGE_NAME</fc>**?**<fc #BF0000>COLUMN=VALUE</fc>**&**<fc #BF0000>COLUMN2=VALUE2</fc>**''
-The request requires a HashMap in JSON format. The column name is used as the key.
+Der Request benötigt eine HashMap im JSON Format. Als Key wird die Spaltenbezeichnung verwendet.
+Beispiel:
-Example:
 <file json>
@@ Line 135: / Line 219: @@
 </file>
-It should be noted that PK columns are not updated.
+Es gilt zu beachten, das PK Spalten nicht aktualisiert werden.
 ==PUT-Response==
-The response returns the complete record in JSON format:
+Der Response liefert den vollständigen Datensatz im JSON Format:
 <file json>
@@ Line 155: / Line 239: @@
 ==DELETE-Request (Delete)==
-Delete exactly one record:
+Genau einen Datensatz löschen:
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/data/**<fc #BF0000>STORAGE_NAME</fc>**/**<fc #BF0000>PRIMARY_KEY</fc>**''
-If the PK is composed of several columns, the query parameters must be used:
+Wenn der PK aus mehreren Spalten zusammengesetzt ist, müssen die Query Parameter verwendet werden:
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/data/**<fc #BF0000>STORAGE_NAME</fc>**?**<fc #BF0000>PKCOLUMN=VALUE</fc>**&**<fc #BF0000>PKCOLUMN2=VALUE2</fc>**''
 ==DELETE-Response==
-The response returns the number of deleted records in JSON format (as number):
+Der Response liefert die Anzahl der gelöschten Datensätze im JSON Format (als Nummer):
 <file json>
@@ Line 169: / Line 253: @@
 </file>
-==OPTIONS-Request (Meta Data)==
+==OPTIONS-Request (Meta Daten)==
-Request Meta Data:
+Meta Daten abfragen:
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/data/**<fc #BF0000>STORAGE_NAME</fc>**''
 ==OPTIONS-Response==
-The response returns the meta data in JSON format:
+Der Response liefert die Meta Daten im JSON Format:
 <file json>
@@ Line 322: / Line 406: @@
 \\
-==== Call actions ====
+==== Aufruf von Actions ====
-The [[jvx:communication:calling_server_action|server-side actions]] can be called directly from the life-cycle object as well as from available business objects. It's also possible to use parameters.
+Die [[jvx:communication:calling_server_action|Server-side Actions]] können sowohl direkt vom Life-cycle Objekt als auch von verwendeten Business Objekten aufgerufen werden. Die Parameter-Übergabe ist ebenfalls möglich.
-  * [[#get-request|Action without parameter]]
+  * [[#get-request|Action ohne Parameter]]
-  * [[#postput-Request|Action with parameter]]
+  * [[#postput-Request|Action mit Parameter]]
 == GET-Request ==
-Call a server-side action (without parameter):
+Aufruf einer Server-side Action (ohne Parameter):
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/action/**<fc #BF0000>ACTION_NAME</fc>**''
-Call a method from a business object (without parameter):
+Aufruf einer Methode eines Business Objektes (ohne Parameter):
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/object/**<fc #BF0000>OBJECT_NAME</fc>**/**<fc #BF0000>ACTION_NAME</fc>**''
 == GET-Response ==
-The response returns the return value of the action in JSON format.
+Der Response liefert den Rückgabewert der Action im JSON Format.
 == POST/PUT-Request ==
-Call a serer-side action (with parameter):
+Aufruf einer Server-side Action (mit Parameter):
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/action/**<fc #BF0000>ACTION_NAME</fc>**''
-Call a method from a business object (with parameter):
+Aufruf einer Methode eines Business Objektes (mit Parameter):
 ''<nowiki>http://server:port/webapp/services/rest/</nowiki>**<fc #BF0000>APPLICATION_NAME</fc>**/**<fc #BF0000>LIFECYCLE_CLASS</fc>**/object/**<fc #BF0000>OBJECT_NAME</fc>**/**<fc #BF0000>ACTION_NAME</fc>**''
-The request requires an array of objects populated with the parameters for the action.
+Der Request benötigt ein Array von Objekten, befüllt mit den Parametern für die Action.
-Example:
+Beispiel:
 Action:
@@ Line 370: / Line 454: @@
 == POST/PUT-Response ==
-The response returns the return value of the action in JSON format.
+Der Response liefert den Rückgabewert der Action im JSON Format.
-===== Examples =====
+===== Anwendungsbeispiele =====
-Using php:
+==== Integration ====
+Mittels php:
 <file php>
@@ Line 389: / Line 475: @@
 curl_close($ch);
+</file>
+Mittels Javascript:
+<file html rest.html>
+<html>
+<head>
+<script>
+function doRest() {
+    const http = new XMLHttpRequest();
+    const url='https://<server>/DB/services/rest/League/Standings/action/getResults';
+    http.open("POST", url, true, 'user', 'password');
+    http.withCredentials = true;
+    http.send("[88]");
+    http.onreadystatechange=(e)=>
+    {
+	if (http.readyState == 4)
+	{
+	    console.log(atob(eval(http.responseText)));
+	}
+    }
+}
+</script>
+</head>
+<body>
+<button type="button" onclick="doRest()">REST call</button>
+</body>
+</html>
 </file>
 \\
-[[https://blog.sibvisions.com/2017/10/23/angularjs-4-with-visionx-and-jvx-rest-services/|AngularJS 4 with VisionX and JVx REST services]]
+[[https://blog.sibvisions.com/2017/10/23/angularjs-4-with-visionx-and-jvx-rest-services/|AngularJS 4 with VisionX and JVx REST services]] \\
-[[https://blog.sibvisions.com/2015/06/15/angularjs-with-jvx-in-action/|AngularJS with JVx in action]]
+[[https://blog.sibvisions.com/2015/06/15/angularjs-with-jvx-in-action/|AngularJS with JVx in action]] \\
+[[https://blog.sibvisions.com/2016/02/29/using-oracle-jet-with-visionxjvx/|Oracle JET with VisionX/JVx]] \\
+==== JUnit Tests ====
+[[https://sourceforge.net/p/jvx/code/HEAD/tree/trunk/java/library/test/com/sibvisions/rad/server/http/rest/TestCallService.java|TestCallService]] für die Lifecycle Objekte: [[https://sourceforge.net/p/jvx/code/HEAD/tree/trunk/java/library/rad/apps/demo/src.server/demo/Session.java|Session]] und [[https://sourceforge.net/p/jvx/code/HEAD/tree/trunk/java/library/rad/apps/demo/src.server/demo/special/Address.java|Address]]
 \\
-**<fs 20px>Note</fs>**
+**<fs 20px>Hinweis</fs>**
-For action calls, the correct data types must be used! In general, it is best to dispense with primitive data types, as parameters, and instead of using arrays, the List Interface should be used. It is also recommended to use Number for all numerical values. This avoids problems due to JSON serialization.
+Bei Action calls müssen die korrekten Datentypen verwendet werden! Generell sollte auf primitive Datentypen, als Parameter, verzichtet und anstatt von Arrays sollte das List Interface verwendet werden. Weiters empfiehlt sich die Nutzung von Number für alle numerischen Werte. Dadurch werden Probleme aufgrund der JSON Serialisierung vermieden.
-The life-cycle name should be the fully qualified class name, with package. If only the simple class name is used, JVx will try to find a matching class. If several classes are considered, then no class is used. You can optionally define a search path in the config.xml of the application:
+Als Life-Cycle Name sollte der Voll qualifiziert Klassenname, mit Package, verwendet werden. Wenn nur der simple Klassen Name verwendet wird, versucht JVx eine passende Klasse zu ermitteln. Sollten mehrere Klassen in Frage kommen, dann wird keine Klasse verwendet. Sie können optional einen Suchpfad in der config.xml der Applikation definieren:
 <file xml>
@@ Line 415: / Line 535: @@
 </file>
-Additional information about this feature is available in our [[https://oss.sibvisions.com/index.php?do=details&task_id=534|Support System]]
+Weitere Details über dieses Feature finden Sie im [[https://oss.sibvisions.com/index.php?do=details&task_id=534|Support System]].