AgileApps Support Wiki

Difference between revisions of "AJAX and REST"

From AgileApps Support Wiki
imported>Aeric
 
(12 intermediate revisions by 2 users not shown)
Line 16: Line 16:
The code is expected to be executed as part of a [[Form]], either as part of a [[Field Script]] or a [[Form Script]]. It builds up an XML string to send to a REST API. In this case, it creates the input XML required by the REST [[REST API:exec Resource|exec]] API, which executes a method in a Java class. And then tells the API to return JSON, which allows individual elements to be accessed by specifying little more than a JavaScript path.
The code is expected to be executed as part of a [[Form]], either as part of a [[Field Script]] or a [[Form Script]]. It builds up an XML string to send to a REST API. In this case, it creates the input XML required by the REST [[REST API:exec Resource|exec]] API, which executes a method in a Java class. And then tells the API to return JSON, which allows individual elements to be accessed by specifying little more than a JavaScript path.


:<syntaxhighlight lang="javascript" enclose="div">
For more information about using AJAX in a form, see the tech community article [https://tech.forums.softwareag.com/t/how-to-invoke-a-class-from-formscript-using-ajax/237541 How to invoke a class from formscript using AJAX].
    // Create the structure to send 
    var paramValue = getTextFieldValue(_sdForm, "someField");
    var inputXML = "<platform>"
                + "  <execClass>"
                + "    <clazz>com.platform.yourCompany.somePackage.someClass</clazz>"
                + "    <method>someMethod</method>"
                + "    <param1>" + paramValue + "</param1>"
                + "  </execClass>"
                + "</platform>";
 
    // Use jQuery's ajax method to invoke the REST API
    $.ajax({
      type: 'POST',
      url: '/networking/rest/class/operation/exec',
      contentType: 'application/xml',
      Accept:'application/json',
      data: inputXML,
      dataType: 'json',
      success: function (data)
      {
        // Call succeeded.
        if (data.platform.execClass.someParam) {
          // Copy data to form fields.
          setTextFieldValue(_sdForm, "field_name",
                            data.platform.execClass.someParam);
        } else {
          alert("No data returned.");
        } 
      } // End of success function
 
    }); // End of AJAX call
</syntaxhighlight>
 
;How it works:
# <tt>_sdForm</tt> - A pointer to the current form.
# <tt>inputXML</tt> - This is the XML structure that will be passed in the call.
# <tt>.ajax</tt> - The jQuery method to call a web service.
# <tt>type</tt> - The type of request to make - an http <tt>GET</tt> or <tt>POST</tt>.
# <tt>url</tt> - The URL to access. In the example, a relative URL is specified.
# <tt>contentType</tt> - The type of data being sent. In this case, the type is XML.
# <tt>Accept</tt> - The type of data that should be returned. Here, they type is JSON.
# <tt>data</tt> - The data parameter. On input, pass the <tt>inputXML</tt>. On output, it contains whatever structure is sent back.
# <tt>success</tt> - Specifies the function to execute when the call succeeds.
# <tt>function</tt> - Defines an inline ''anonymous'' function (one without a name) that has the code to execute.
# <tt>data.platform.execClass.someParam</tt> - The [[REST API:exec Resource|exec]] API returns a structure that is virtually identical to the input structure. Except here, it is in JSON format, which allows individual elements to be accessed by specifying their JavaScript path. So:
#:* <tt>data</tt> - The string returned by the call, and passed to the function.
#:* <tt>platform</tt> - The root element of the returned structure.
#:* <tt>execClass</tt> - The element that contains the key/value pairs that came back
#:* <tt>someParam</tt> - A parameter element
# <tt>setTextFieldValue</tt> - One of the platform's [[JavaScript Functions]], used to set a value in a form.
# <tt>alert</tt> - Display a message when no data comes back.
 
''Learn more:''
:For a fully-workout example, see [[Java Code Samples#Invoke Web Services Programmatically]]. The first part creates a class that accesses a web service. The last part uses an AJAX call to invoke that method, using the platform's REST APIs.


====Using AJAX in a JSP Page====
====Using AJAX in a JSP Page====
When you create a [[Pages|Page]] in the platform, you are creating a JSP page. You can embed Java code in that page, and use it to directly interact with the platform. Or you can use AJAX and the REST APIs, whichever is easiest.
When you create a [[Pages|Page]] in the platform, you are creating a JSP page. You can embed Java code in that page, and use it to directly interact with the platform. Or you can use AJAX and the REST APIs, whichever is easiest.


=====Basic AJAX Syntax=====
For information on using AJAX in a JSP page, see the tech community article [https://tech.forums.softwareag.com/t/invoking-rest-api-calls-using-ajax-in-agileapps-pages/237543 Invoking REST API Calls using AJAX in AgileApps Pages].
In this syntax description, <tt>xmlhttp</tt> is the communications object. You'll learn how to make one in the example that follows. For now, the focus is on the methods you use to interact with it.
:<syntaxhighlight lang="javascript" enclose="div">
xmlhttp.open(method, resource_url, async);
xmlhttp.send();                  // GET or DELETE
xmlhttp.send("request data");    // POST or PUT
</syntaxhighlight>
 
:where:
::* ''method'' is <tt>GET</tt>, <tt>POST</tt>, <tt>PUT</tt>, or <tt>DELETE</tt>
::* ''resource_url'' is the resource you are accessing
::* ''async'' is a boolean.
:::* If <tt>true</tt>, you put processing code into an <tt>onreadystatechange</tt> function, and the page continues  displaying itself while the request is being processed. Whenever the response from the server is received, it is integrated into the page. (That is the preferred way to do things.)
:::* If <tt>false</tt>, you put processing code after the <tt>send()</tt> statement. (You don't need a function, but the page may appear to hang while it is being rendered, so this procedure is not recommended.)
 
:;Considerations:
:* Most often, you'll want to make asynchronous requests. They're slightly harder to write, because you have to add the  <tt>onreadystatechange</tt> function. But the page won't hang while waiting for the server to respond.
:* The platform's [[REST API]]s return XML, by default. To get back JSON data, you append "?alt=JSON" to the URL.
:* When a resource that responds to a GET request takes additional data, the data is included by appending a ''query string'' to the URL, in order to [[Specifying_Query_Parameters_in_REST_APIs|Specify Query Parameters]].
:* Platform GET (read), PUT (update), and DELETE requests return 200 on success.
:* Platform POST (create) requests return 201 on success.
 
{{Tip|In Firefox, the [http://getfirebug.com/ Firebug] plugin makes it possible to debug JavaScript. You can set breakpoints, see the content of variables, and review the structure of the internal DOM after elements have been dynamically added.}}
 
=====Example: Retrieving Data with a GET Request =====
{{:HowTo:Use AJAX and REST in a Web Page to GET data}}
 
=====POST/PUT Syntax=====
When there is too much data to send using [[Specifying_Query_Parameters_in_REST_APIs|Query Parameters]], a REST API will require you to send the data in a POST request (to add something new) or in a PUT request (to update something existing). You'll specify add a request header that tells the platform what form the data is in:
:<syntaxhighlight lang="java" enclose="div">
xmlhttp.open(method,resource_url,async);
xmlhttp.setRequestHeader("Content-type","application/xml");  // or "application/json"
xmlhttp.send("request data");   
</syntaxhighlight>


=====Example: Sending Data with a POST Request =====
=====Example: Retrieving Data with a GET Request=====
{{:HowTo:Use AJAX and REST in a Web Page to POST data}}
To view the example on how to retrieve data using a GET request, see the tech community article [https://tech.forums.softwareag.com/t/retrieving-data-with-a-get-request/237537 Retrieving Data with a GET Request].


=====Example: Validating a CSRF session for POST, PUT, and DELETE=====
=====Example: Validating a CSRF session for POST, PUT, and DELETE=====
You have to validate a CSRF session for POST, PUT, and DELETE requests. The following section provides sample codes for validating CSRF sessions for Form Submissions and REST APIs. For both validations, the CSRF cookie name in AgileApps is "XSRF-TOKEN". The validations can be performed using JavaScript or jQuery.
You have to validate a CSRF session for POST, PUT, and DELETE requests. For information about validating a CSRF session, see the Tech Community article at [https://tech.forums.softwareag.com/t/validating-a-csrf-session-for-post-put-and-delete/237538 Validating a CSRF session for POST, PUT, and DELETE]. This article provides sample codes for validating CSRF sessions for Form Submissions and REST APIs.
 
======For Forms======
:*'''Method 1: Using JavaScript'''
::To all the existing form fields, add a hidden field having a CSRF token value that is taken from the cookie "XSRF-TOKEN".
:Sample HTML code that you can place inside the form element is as follows:
 
:<syntaxhighlight lang="javascript" enclose="div">
<input type='hidden' name='X-XSRF-TOKEN' id='X-XSRF-TOKEN' value=''></input>
</syntaxhighlight>


{{Note|Ensure to add the header X-XSRF-TOKEN with value of xsrfToken from the login response.}}


:Sample code to get the value of "XSRF-TOKEN"
=====Example: Retrieving a JSON output of Dynamic Search API on a custom object=====
//You can use any approach to get the cookie value. This is an example.<br>
{{Note| This is applicable only for the legacy UI}}
:<syntaxhighlight lang="javascript" enclose="div">
To retrieve a JSON output of Dynamic Search API on a custom object, refer to this example:
function getCookie(cookieName) {
var decodedCookie = decodeURIComponent(document.cookie);
var ca = decodedCookie.split(';');
for(var i = 0; i <ca.length; i++) {
        var c = ca[i];
        while (c.charAt(0) == ' ') {
            c = c.substring(1);
        }
        if (c.indexOf(cookieName) == 0) {  
console.log(c.substring(cookieName.length+1, c.length));
            return c.substring(cookieName.length+1, c.length);
        }  
    }  
    return "";
}
var token = getCookie('XSRF-TOKEN');
</syntaxhighlight>


//assigning value to a hidden element in the form
:<syntaxhighlight lang="javascript" enclose="div">
document.getElementById('X-XSRF-TOKEN').value = token;
</syntaxhighlight><noinclude>
:*'''Method 2: Using jQuery'''
:<syntaxhighlight lang="javascript" enclose="div">
var token = $.cookie('XSRF-TOKEN');,assign it to the form hidden field
$('#X-XSRF-TOKEN').val(token );
</syntaxhighlight>
======For REST APIs======
Intercept the ajax request and add setrequestheader. The request header is  "X-XSRF-TOKEN" and the value for the header is derived from the cookie "XSRF-TOKEN".
:*'''Method 1: Using JavaScript'''
:<syntaxhighlight lang="javascript" enclose="div">
var send = XMLHttpRequest.prototype.send,
        token = getCookie('XSRF-TOKEN')
          XMLHttpRequest.prototype.send = function(data) {           
                this.setRequestHeader('X-XSRF-TOKEN', token );
                return send.apply(this, arguments);
          };
</syntaxhighlight>
   
:*'''Method 2: Using jQuery'''
:<syntaxhighlight lang="javascript" enclose="div">
:<syntaxhighlight lang="javascript" enclose="div">
var recordData = [];
$.ajax({
$.ajax({
         type: 'POST',
         type: 'GET',
         url: domain +  url ,
         url: '/networking/rest/record/cases?fieldList=subject,description&alt=json',
         processData: true,
         processData: true,
         dataType: 'json',
         dataType: 'json',
         beforeSend: function(xhr){
         async:false,
            xhr.setRequestHeader('X-XSRF-TOKEN', $.cookie('XSRF-TOKEN'));
        },
         success: function(data)
         success: function(data)
         { }
         {
if (data.platform.record instanceof Array )
{
recordData = data.platform.record ;
}
else if ( typeof data.platform.record != 'undefined' )
{
recordData.push(data.platform.record);
}
alert(recordData);
}
});
});
</syntaxhighlight>
</syntaxhighlight>

Latest revision as of 05:24, 17 May 2024

The combination of JavaScript and the platform's REST APIs lets you build a lot of power into a page that displays on a client-side browser.

About AJAX

AJAX is the name given to a set of JavaScript functions that let you connect to a server, get back data, and parse the data into something usable. It originally stood for "Asynchronous JavaScript and XML", but it can also use the JSON format for data interchange.

Perhaps the best summary of AJAX comes from the w3c.schools tutorial:

"AJAX is the art of exchanging data with a server, and updating parts of a web page, without reloading the whole page."

While an arbitrary string can be passed to or from the server, the two most popular formats by far are XML and JSON. The platform understands both, so you can choose the flavor you prefer. (A common variation is to send XML data to the platform because it's easy to build up strings in XML format, and then get JSON back because that is the easiest format to parse in JavaScript.)

Learn more: AJAX Tutorial

Using AJAX in a Form

The jQuery functions included in the platform make it as simple as possible to make an AJAX call.

The code is expected to be executed as part of a Form, either as part of a Field Script or a Form Script. It builds up an XML string to send to a REST API. In this case, it creates the input XML required by the REST exec API, which executes a method in a Java class. And then tells the API to return JSON, which allows individual elements to be accessed by specifying little more than a JavaScript path.

For more information about using AJAX in a form, see the tech community article How to invoke a class from formscript using AJAX.

Using AJAX in a JSP Page

When you create a Page in the platform, you are creating a JSP page. You can embed Java code in that page, and use it to directly interact with the platform. Or you can use AJAX and the REST APIs, whichever is easiest.

For information on using AJAX in a JSP page, see the tech community article Invoking REST API Calls using AJAX in AgileApps Pages.

Example: Retrieving Data with a GET Request

To view the example on how to retrieve data using a GET request, see the tech community article Retrieving Data with a GET Request.

Example: Validating a CSRF session for POST, PUT, and DELETE

You have to validate a CSRF session for POST, PUT, and DELETE requests. For information about validating a CSRF session, see the Tech Community article at Validating a CSRF session for POST, PUT, and DELETE. This article provides sample codes for validating CSRF sessions for Form Submissions and REST APIs.

Notepad.png

Note: Ensure to add the header X-XSRF-TOKEN with value of xsrfToken from the login response.

Example: Retrieving a JSON output of Dynamic Search API on a custom object

Notepad.png

Note: This is applicable only for the legacy UI

To retrieve a JSON output of Dynamic Search API on a custom object, refer to this example:

<syntaxhighlight lang="javascript" enclose="div">

var recordData = []; $.ajax({ 

        type: 'GET',
        url: '/networking/rest/record/cases?fieldList=subject,description&alt=json',
        processData: true,
        dataType: 'json',
        async:false,
        success: function(data)
        {

if (data.platform.record instanceof Array ) { recordData = data.platform.record ; } else if ( typeof data.platform.record != 'undefined' ) { recordData.push(data.platform.record); } alert(recordData); } }); </syntaxhighlight>

Retrieved from "https://agileappscloud.info/aawiki-src/index.php?title=AJAX_and_REST&oldid=30646"