Documentation

Trace:

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
jvx:common:util:rest [2018/02/08 08:35]
admin
jvx:common:util:rest [2022/11/17 11:13] (current)
admin
Line 1: Line 1:
-~~Title: REST service~~+~~Title: REST Services~~
  
-We define the business logic with [[jvx:​server:​lco:​objects|life-cycle objects]] on the server side. The access authorization of an application is checked by a [[jvx:​server:​security:​manager|security manager]]. The business logic is usually available via master- or subconnections from the client.+We define the business logic with [[jvx:​server:​lco:​objects|life cycle objects]] on the server side. The access authorization of an application is checked by a [[jvx:​server:​security:​manager|security manager]]. The business logic is usually available via master- or subconnections from the client.
  
 In order to complete the technology independence,​ the complete business logic of an application is also available via REST. In order to complete the technology independence,​ the complete business logic of an application is also available via REST.
Line 7: Line 7:
 For the use of the REST services, the authentication with username and password is necessary. [[https://​en.wikipedia.org/​wiki/​Basic_access_authentication|BASIC]] is used as the authentication mechanism. The credentials are checked by the security manager of the application as usual. You do not need to change a source code line to integrate the REST services. For the use of the REST services, the authentication with username and password is necessary. [[https://​en.wikipedia.org/​wiki/​Basic_access_authentication|BASIC]] is used as the authentication mechanism. The credentials are checked by the security manager of the application as usual. You do not need to change a source code line to integrate the REST services.
  
-=====How ​it works=====+=====How ​It Works=====
  
 The REST implementation in JVx has been implemented with [[http://​www.restlet.org/​|Restlet]]. To use the REST services, the deployment descriptor must be configured as follows: The REST implementation in JVx has been implemented with [[http://​www.restlet.org/​|Restlet]]. To use the REST services, the deployment descriptor must be configured as follows:
Line 30: Line 30:
 With this configuration,​ the following services are available: With this configuration,​ the following services are available:
  
-===== Available ​services ​=====+===== Available ​Services ​=====
  
-====Storage ​access ​ ​(CRUD, ​Meta Data)====+==== Administration ==== 
 + 
 +Various services are available for the administration. These can only be used by POST requests in the standard case. However, if certain custom services have been registered, they can also be addressed via GET request. 
 + 
 +The following services are available by default: 
 + 
 +  * [[#​test_authentication|Test authentication]] 
 +  * [[#​change_password|Change password]] 
 +  * [[#​check_database|Check database]] 
 + 
 +=== Test Authentication === 
 + 
 +Test URL:\\  
 +''<​nowiki>​http://​server:​port/​webapp/​services/​rest/</​nowiki>​**<​fc #​BF0000>​APPLICATION_NAME</​fc>​**/​_admin/​**<​fc #​BF0000>​testAuthentication</​fc>​**''​ \\  
 +or \\  
 +''<​nowiki>​http://​server:​port/​webapp/​services/​rest/</​nowiki>​**<​fc #​BF0000>​APPLICATION_NAME</​fc>​**/​_admin/​**<​fc #​BF0000>​testAuthentication</​fc>​**/​**<​fc #​BF0000>​parameter</​fc>​**''​ 
 + 
 +The request requires a HashMap in JSON format. 
 + 
 +Example: 
 + 
 +<file json> 
 +{ "​username"​ : "​admin",​ 
 +  "​password"​ : "​adminpassword"​ 
 +
 +</​file>​ 
 + 
 +The username can also be omitted. In this case, the parameter from the URL will be used as the username. 
 + 
 +== POST-Response == 
 + 
 +If the login was successful, no response is generated and the status code is 204 (SUCCESS_NO_CONTENT). 
 + 
 +=== Change Password === 
 + 
 +Test URL:\\  
 +''<​nowiki>​http://​server:​port/​webapp/​services/​rest/</​nowiki>​**<​fc #​BF0000>​APPLICATION_NAME</​fc>​**/​_admin/​**<​fc #​BF0000>​changePassword</​fc>​**''​ \\  
 +or \\  
 +''<​nowiki>​http://​server:​port/​webapp/​services/​rest/</​nowiki>​**<​fc #​BF0000>​APPLICATION_NAME</​fc>​**/​_admin/​**<​fc #​BF0000>​changePassword</​fc>​**/​**<​fc #​BF0000>​parameter</​fc>​**''​ 
 + 
 +The request requires a HashMap in JSON format. 
 + 
 +Example: 
 + 
 +<file json> 
 +{ "​username"​ : "​admin",​ 
 +  "​oldpassword"​ : "​oldpassword",​ 
 +  "​newpassword"​ : "​newpassword"​ 
 +
 +</​file>​ 
 + 
 +The username can also be omitted. In this case, the parameter from the URL will be used as the username. 
 + 
 +== POST-Response == 
 + 
 +If the password has been changed, no response is generated and the status code is 204 (SUCCESS_NO_CONTENT). 
 + 
 +=== Check database === 
 + 
 +Test URL:\\  
 +''<​nowiki>​http://​server:​port/​webapp/​services/​rest/</​nowiki>​**<​fc #​BF0000>​APPLICATION_NAME</​fc>​**/​_admin/​**<​fc #​BF0000>​checkDB</​fc>​**''​ 
 + 
 +== GET-Response == 
 + 
 +If the check was successful, no response is generated and the status code is 204 (SUCCESS_NO_CONTENT). If database is not available, status code 500 (SERVER_ERROR_INTERNAL) will be returned. It's also possible that the configuration can't be found. In this case, status code 503 (SERVER_ERROR_SERVICE_UNAVAILABLE) will be returned. 
 + 
 +=== Custom Services === 
 + 
 +If you want to register your own service at runtime, this can be done by 
 + 
 +<code java> 
 +UserService.register(String pApplicationName,​ String pAction, ICustomServiceDelegate pDelegate);​ 
 +UserService.unregister(String pApplicationName,​ String pAction) 
 +</​code>​ 
 + 
 +The service can be addressed either via GET or POST request, depending on whether ** // ICustomServiceGetDelegate // ** or ** // ICustomServicePostDelegate // ** is used. 
 + 
 +Test URL: 
 + 
 +''<​nowiki>​http://​server:​port/​webapp/​services/​rest/</​nowiki>​**<​fc #​BF0000>​APPLICATION_NAME</​fc>​**/​_admin/​**<​fc #​BF0000>​ACTION</​fc>​**''​ \\  
 +or \\  
 +''<​nowiki>​http://​server:​port/​webapp/​services/​rest/</​nowiki>​**<​fc #​BF0000>​APPLICATION_NAME</​fc>​**/​_admin/​**<​fc #​BF0000>​ACTION</​fc>​**/​**<​fc #​BF0000>​parameter</​fc>​**''​ 
 + 
 +====Storage ​Access ​ ​(CRUD, ​Metadata)====
  
   * [[#​get-request_select|Select]]   * [[#​get-request_select|Select]]
Line 38: Line 121:
   * [[#​put-request_update|Update]]   * [[#​put-request_update|Update]]
   * [[#​delete-request_delete|Delete]]   * [[#​delete-request_delete|Delete]]
-  * [[#​options-request_meta_data|Meta Data]]+  * [[#​options-request_meta_data|Metadata]]
  
 ==GET-Request (Select)== ==GET-Request (Select)==
Line 53: Line 136:
 The query parameters can also be used to perform filtering with columns that are not PK columns. The query parameters can also be used to perform filtering with columns that are not PK columns.
  
-Read more about [[https://​blog.sibvisions.com/​2017/​10/​30/​jvx-rest-interface-update/​|complex query parameters]]?+Read more about [[https://​blog.sibvisions.com/​2017/​10/​30/​jvx-rest-interface-update/​|complex query parameters]].
  
 ==GET-Response== ==GET-Response==
Line 117: Line 200:
 == PUT-Request (Update) == == PUT-Request (Update) ==
  
-Update a requord ​with Primary Key:+Update a record ​with Primary Key:
 ''<​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>​**''​ ''<​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:+If the PK is composed of several columnsor if the records are not to be identified via the PK, the query parameters must be used:
 ''<​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>​**''​ ''<​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>​**''​
  
Line 169: Line 252:
 </​file>​ </​file>​
  
-==OPTIONS-Request (Meta Data)==+==OPTIONS-Request (Metadata)==
  
-Request ​Meta Data:+Request ​Metadata:
 ''<​nowiki>​http://​server:​port/​webapp/​services/​rest/</​nowiki>​**<​fc #​BF0000>​APPLICATION_NAME</​fc>​**/​**<​fc #​BF0000>​LIFECYCLE_CLASS</​fc>​**/​data/​**<​fc #​BF0000>​STORAGE_NAME</​fc>​**''​ ''<​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== ==OPTIONS-Response==
  
-The response returns the meta data in JSON format:+The response returns the metadata ​in JSON format:
  
 <file json> <file json>
Line 322: Line 405:
  
 \\ \\
-==== Call actions ​====+==== Call 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.+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.
  
   * [[#​get-request|Action without parameter]]   * [[#​get-request|Action without parameter]]
Line 374: Line 457:
  
 ===== Examples ===== ===== Examples =====
 +
 +==== Integration ====
  
 Using php: Using php:
Line 389: Line 474:
  
 curl_close($ch);​ curl_close($ch);​
 +</​file>​
 +
 +Using 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>​ </​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]] for the Lifecycle objects: [[https://​sourceforge.net/​p/​jvx/​code/​HEAD/​tree/​trunk/​java/​library/​rad/​apps/​demo/​src.server/​demo/​Session.java|Session]] and [[https://​sourceforge.net/​p/​jvx/​code/​HEAD/​tree/​trunk/​java/​library/​rad/​apps/​demo/​src.server/​demo/​special/​Address.java|Address]]
  
 \\  \\ 
Line 401: Line 520:
 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. 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.
  
-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:​+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:​
  
 <file xml> <file xml>
This website uses cookies for visitor traffic analysis. By using the website, you agree with storing the cookies on your computer.More information