REST Web services
Introduction
The XTEND server provides to AJAX application developers two types of REST Web services which may be called directly from the Web browser via a HTTP request.
- SOAP X3 Web service call via an XTEND interface
- Call of a server script
Only XTEND applications can access those services.
The engine takes into account only the REST requests that have an XTEND session associated via cookie (or URL setup) JSESSIONID.
The XTEND REST services are only available on the XTEND server.
They "encapsulate" the SOAP X3 Web service call.
The structures of REST data exchanged for the setup transfer (keys and data) and the result return (data and messages) are the same as for the SOAP services.
Only the exchange protocol with the customer is different.
Note on SOAP X3 Web services
This section presents the available SOAP X3 Web services as well as the associated data structures.
It is necessary to have a knowledge of SOAP X3 Web services before using XTEND REST services.
Call setups
Mandatory setups
- The call context CAdxCallContext callContext
Contains X3 login information and data on the connection pool processing the query - The publication name of the Web service String publicName defined upon publication
public CAdxCallContext {
//X3 language code
String codeLang;
//X3 user code
String codeUser;
//X3 password
String password;
//Alias of the connection pool on the Web services server
String poolAlias;
//Configuration setups (query string)
String requestConfig;
}
The setups adxwss.optreturn=JSON/XML of the query string requestConfig indicate the type of result (XML by default).
The Web service server detects automatically the XML or JSON format upon entry.
JSON Options
The JSON format proposes options in order to filter the data sent by the Web service.
The options are defined:
- either in the query string requestConfig via setup adxwss.optjson
requestConfig=adxwss.optreturn=JSON&adxwss.optjson={"OPTIONS":"noGoups"} - or in the JSON setups of the object or the sub-program via field "_JSONOPT"
See JSON call setups
The JSON option is a JSON object has at least one of the fields below.
{
OPTIONS:["nolabels","noclobs","nogroups","norows"],
LANG:"ENG",
EXCLUDEGRP:["GRP1","GRP2"],
INCLUDEGRP:["GRP1","GRP2"],
EXCLUDEFLD:["FLD1","FLD2"],
INCLUDEFLD:["FLD1","FLD2"]
}
OPTIONS
noGroups
No publication groups in return
Each setup of the sub-program or field of the object is a String grid.
noRows
No lines in the grids with dim>1
Each setup of the sub-program or field of the object is a String grid.
noLabels
No labels for local menus
noClobs
The clob fields are not re-sent
The OPTION field allows either a setup grid or a single setup (String)
EXCLUDEGRP
Excludes the mentioned groups
INCLUDEGRP
Includes the mentioned content groups
EXCLUDEFLD
Excludes the mentioned fields
EXCLUDEFLD
Includes the mentioned fields
The fields INCLUDE* and EXCLUDE* allow either a String grid or a single String
X3 object key setups
The setup CAdxParamKeyValue objectKeys for the methods of X3 object making keys necessary (Read/Query...).
It is a Field/value code grid
public class CAdxParamKeyValue{
private String key;
private String value;
}
Data setup
The setup String objectXml for an X3 object or String inputXml contains the data for the object or the setups of the sub-program in XML or JSON format.
The JSON format was added for the needs of the AJAX applications.
Example of the call format of the Login Web service AXTDLOGIN of the ASAMPLE site.
JSON setups
JSON option in the call setups: nogroups, norows
{
_JSONOPT:{OPTIONS:["nogroups", "norows"]},
AXPARCOD:["SITCOD", "USRLANG"],
AXPARVAL:["FDBTEST", "FRA"],
AXUSERCODE:"DIS001",
AXPWD:"adonix"
}
XML setups
<PARAM>
<TAB ID="AX_PAR">
<LIN NUM="1">
<FLD NAME="AXPARCOD">SITCOD</FLD>
<FLD NAME="AXPARVAL">FDBTEST</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="AXPARCOD">USRLANG</FLD>
<FLD NAME="AXPARVAL">FRA</FLD>
</LIN>
</TAB>
<GRP ID="AXLOG_PAR">
<FLD NAME="AXUSERCODE">DIS001</FLD>
<FLD NAME="AXPWD">adonix</FLD>
</GRP>
</PARAM>
Sub-program data setup structure
The fields <FLD NAME="FieldName"> represent the sub-program setups and are attached to the publication group
The publication groups are defined in the Web service record associated with the sub-program record.
They are represented by nodes <GRP ID="IdGroup"> for setups in dimension 1 and <TAB ID="IdGroup"> for setups in dimension > 1.
The node <LIN> regroups the fields from a same grid having the same index.
The JSON setups take up the same structure but is is not mandatory to use publication groups.
XML sub-program
<PARAM>
<GRP ID=’GRP1’>
<FLD NAME=’CHAMP’>Value</FLD>
</GRP>
<TAB ID=’GRP2’>
<LIN>
<FLD NAME=’CHAMP1’>Value1</FLD>
<FLD NAME=’CHAMP2’>Value1</FLD>
</LIN>
<LIN>
<FLD NAME=’CHAMP1’>Value1</FLD>
<FLD NAME=’CHAMP2’>Value2</FLD>
</LIN>
</TAB>
</PARAM>
JSON sub-program
/*--- Without the groups ---*/
{
CHAMP:"Value",
CHAMP1:["Value1","Value2"],
CHAMP2:["Value1","Value2"]
}
/*--- With the groups ---*/
{
GRP1:{
CHAMP:"Value"
},
GRP2:[
{
CHAMP1:"Value1",
CHAMP2:"Value1"
},
{
CHAMP1:"Value2",
CHAMP2:"Value2"
}
]
}
X3 object data setup structure
The same structure is used as for sub-programs but the group names are coded depending on the location of the section on screen.
In JSON mode it is not mandatory to specify the group names.
The developer chooses whether or not to specify the group name when using a field of the X3 object whose name alone is not sufficient to identify it.
There may be several fields with the same name in an X3 object.
Example for SOH order
SOH4_1 (lines of the order) corresponds to the 1st section of the 4th screen
XML object
<PARAM>
<GRP ID="SOH0_1">
<FLD NAME="BPCORD">DIS001</FLD>
<FLD NAME="SOHTYP">WEB</FLD>
<FLD NAME="SALFCY">ASN</FLD>
</GRP>
<GRP ID="SOH2_1">
<FLD NAME="STOFCY">ASN</FLD>
</GRP>
<TAB ID="SOH4_1">
<LIN>
<FLD NAME="ITMREF">CUB100</FLD>
<FLD NAME="QTY">50</FLD>
</LIN>
<LIN>
<FLD NAME="ITMREF">CD100</FLD>
<FLD NAME="QTY">10</FLD>
</LIN>
</TAB>
</PARAM>
JSON object
{
BPCORD:"DIS001",
SOHTYP:"WEB",
SALFCY:"ASN",
STOFCY:"ASN",
ITMREF:["CUB100","CD100"],
ITMREF:["50","10"]
}
Services
/*--------------- Call of a SUB-PROGRAM ---------------*/
public CAdxResultXml run(
CAdxCallContext callContext,
String publicName,
String inputXml) throws Exception;
/*--------------- Call of an X3 sub-OBJECT ---------------*/
public CAdxResultXml save(
CAdxCallContext callContext,
String publicName,
String objectXml) throws Exception;
//------------------------------------------
public CAdxResultXml delete(
CAdxCallContext callContext,
String publicName,
CAdxParamKeyValue[] objectKeys) throws Exception;
//------------------------------------------
public CAdxResultXml read(
CAdxCallContext callContext,
String publicName,
CAdxParamKeyValue[] objectKeys) throws Exception;
//------------------------------------------
public CAdxResultXml query(
CAdxCallContext callContext,
String publicName,
CAdxParamKeyValue[] objectKeys,
int listSize) throws Exception;
//------------------------------------------
public CAdxResultXml modify(
CAdxCallContext callContext,
String publicName,
CAdxParamKeyValue[] objectKeys,
String objectXml) throws Exception;
//------------------------------------------
public CAdxResultXml actionObject(
CAdxCallContext callContext,
String publicName,
String actionCode,
CAdxParamKeyValue[] objectKeys) throws Exception;
//------------------------------------------
public CAdxResultXml actionObject(
CAdxCallContext callContext,
String publicName,
String actionCode
String objectXml) throws Exception;
}
Result
The call of a Web service always returns a result object CAdxResultXml which contains:
- Object data or sub-program setups in XML or JSON format
String resultXml - the application messages of type error, warning or information
CAdxMessage messages - technical information on the sub-program execution
CAdxTechnicalInfos technicalInfos
X3 application errors are not returned as exceptions.
The JSON format does not take into account setups of type BLOB containing binary data.
public class CAdxResultXml{
public CAdxMessage[] messages;
public String resultXml;
public int status;
public CAdxTechnicalInfos technicalInfos;
}
public class CAdxMessage {
public String message;
//"1":Information - "2":Warning - "3":Error
public String type;
}
Example of result following the call of Login Web service AXTDLOGIN of the ASAMPLE site.
JSON result
JSON Options: norows and nogroups
{
AXPARCOD:["SITCOD","USRLANG"],
AXPARVAL:["FDBTEST","FRA"]
AXUSERCODE:"DIS001",
AXPWD:"adonix",
AXUSERPROF:"B2B",
AX3SOL:["SOLPAIE","X3V5","XTENDV2"],
AX3FLDR:["PAIE","X3TESTV5","DEMOFRA"],
AX3LANG:["FRA","FRA","FRA"],
AX3USER:["XTEND","JPJ1","OG"],
AXLOGCOD:["NAME","FIRSTNAME","EMAIL","PHONE"],
AXLOGVAL:["DALBO","Frédéric","../FCT/mailto:[email protected]","0001020304"]
SHIPADR1:["Sage Lyon new","Sage MGE","Sage PARIS"],
SHIPCITY:["LYON","Echirolles","PARIS"],
SHIPZIP:["69443","38130","75834"]
}
XML result
<RESULT>
<TAB DIM="20" ID="AX_PAR" SIZE="2">
<LIN NUM="1">
<FLD NAME="AXPARCOD" TYPE="Char">SITCOD</FLD>
<FLD NAME="AXPARVAL" TYPE="Char">FDBTEST</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="AXPARCOD" TYPE="Char">USRLANG</FLD>
<FLD NAME="AXPARVAL" TYPE="Char">FRA</FLD>
</LIN>
</TAB>
<GRP ID="AXLOG_PAR">
<FLD NAME="AXUSERCODE" TYPE="Char">DIS001</FLD>
<FLD NAME="AXPWD" TYPE="Char">adonix</FLD>
<FLD NAME="AXUSERPROF" TYPE="Char">B2B</FLD>
</GRP>
<TAB DIM="10" ID="AXLOG_X3" SIZE="3">
<LIN NUM="1">
<FLD NAME="AX3SOL" TYPE="Char">SOLPAIE</FLD>
<FLD NAME="AX3FLDR" TYPE="Char">PAIE</FLD>
<FLD NAME="AX3LANG" TYPE="Char">FRA</FLD>
<FLD NAME="AX3USER" TYPE="Char">XTEND</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="AX3SOL" TYPE="Char">X3V5</FLD>
<FLD NAME="AX3FLDR" TYPE="Char">X3TESTV5</FLD>
<FLD NAME="AX3LANG" TYPE="Char">FRA</FLD>
<FLD NAME="AX3USER" TYPE="Char">JPJ1</FLD>
</LIN>
<LIN NUM="3">
<FLD NAME="AX3SOL" TYPE="Char">XTENDV2</FLD>
<FLD NAME="AX3FLDR" TYPE="Char">DEMOFRA</FLD>
<FLD NAME="AX3LANG" TYPE="Char">FRA</FLD>
<FLD NAME="AX3USER" TYPE="Char">OG</FLD>
</LIN>
</TAB>
<TAB DIM="50" ID="AXLOG_RES" SIZE="4">
<LIN NUM="1">
<FLD NAME="AXLOGCOD" TYPE="Char">NAME</FLD>
<FLD NAME="AXLOGVAL" TYPE="Char">DALBO</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="AXLOGCOD" TYPE="Char">FIRSTNAME</FLD>
<FLD NAME="AXLOGVAL" TYPE="Char">Frédéric</FLD>
</LIN>
<LIN NUM="3">
<FLD NAME="AXLOGCOD" TYPE="Char">EMAIL</FLD>
<FLD NAME="AXLOGVAL" TYPE="Char">[email protected]</FLD>
</LIN>
<LIN NUM="4">
<FLD NAME="AXLOGCOD" TYPE="Char">PHONE</FLD>
<FLD NAME="AXLOGVAL" TYPE="Char">0001020304</FLD>
</LIN>
</TAB>
<TAB DIM="20" ID="LOGINSHIP" SIZE="3">
<LIN NUM="1">
<FLD NAME="SHIPADR1" TYPE="Char">Sage Lyon new</FLD>
<FLD NAME="SHIPCITY" TYPE="Char">LYON</FLD>
<FLD NAME="SHIPZIP" TYPE="Char">69443</FLD>
</LIN>
<LIN NUM="2">
<FLD NAME="SHIPADR1" TYPE="Char">Sage MGE</FLD>
<FLD NAME="SHIPCITY" TYPE="Char">Echirolles</FLD>
<FLD NAME="SHIPZIP" TYPE="Char">38130</FLD>
</LIN>
<LIN NUM="3">
<FLD NAME="SHIPADR1" TYPE="Char">Sage PARIS</FLD>
<FLD NAME="SHIPCITY" TYPE="Char">PARIS</FLD>
<FLD NAME="SHIPZIP" TYPE="Char">75834</FLD>
</LIN>
</TAB>
</RESULT>
XTEND REST Web services
Principle of the functioning
Here are the various processing steps of a REST query:
1. Receipt of the HTTP query by the ajax servlet of XTEND server
2. Search of the associated XTEND session
Via the cookie or the setup of query JSESSIONID
-> Error if no session could be found
3. Analysis of the URL to infer the details of the XTEND site and the service type
Several sites may be open at the same time for an XTEND session
-> Error if site could not be found
4. Execution of the server script or the call of X3 SOAP Web service
Server script processing
1. Read of the access path in the URL
2. Read and compilation of the JavaScript script
3. Execution of the script
- The script makes it possible to access the session data and to call X3 SOAP Web services
- The print instruction of the script is used to send the response (XML, JSON, HTML...)
X3 SOAP Web service call processing
1. Read of the XTEND interface code in the URL
The interface refers tp a SOAP Web service
-> Error if the interface is not declared in the site
2. Call setup creation
- The XML or JSON data are read in the body of the query
- The keys are read in the 'Query String'
- The type of result requested -XML or JSON- is read in the HTTP xtd-accept header
3. Creation of the call context for the SOAP Web service
- The entry point (URL) is given by the XTEND site (Web service pool of the site or interface)
- The XTEND session provides the X3 user code and the language password
4. Call to the SOAP Web service.
5. Creation of the result
- The messages are transferred to the HTTP header
xtd-msg-error, xtd-msg-warning,xtd-msg-info - The XML/JSON data sent by the SOAP Web service are transferred without modification to the body of the query
URL format
http://host:port/xtend/ajax/x3sol/x3folder/xtdsite/type/id[/méthode][?Paramètres]
HTTP POST or GET method
x3sol
X3 solution code
x3folder
X3 folder code
xtdsite
XTEND site code
type
INT for the call to an XTEND interface
SCRIPT for the call to an XTEND server script
id
Interface code
or
Access path to the script with respect to the server script directory of the XTEND site
method
Code of the X3 object method
QUERY, R Read, S Save, M Modify,D Delete
Setups
Query string which may contain:
- The key fields of an X3 object
- Setups of a left list
- The JSON options via key _JSONOPT if they are not used in the data setups
Examples
Script
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/SCRIPT/ajaxTest1.js
Sub-program
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/AXTDLOGIN
Objet X3 - Read
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/R?FRMCOD=0901000002
&_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D
X3 object left list
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/QUERY?_COUNT=10&FRMCOD=09*
&_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D
Sending data
The setups of type data other than those of the query string are used in the body of the HTTP query.
The format of setups for the call to an XTEND interface are given by the ContentType of the HTTP query:
- application/json
The structure of data must comply with the expected format - application/xml
The XML data must comply with the expected format - application/x-www-form-urlencoded
In this case the list of fields/values is considered as being a JSON object complying with the expected format
The default ContentType is application/json.
The format of data for the call to a server script is compulsorily application/json.
Result
When calling to an XTEND interface, it is possible to require an XML return format (application/xml) or JSON (application/json) by valuing the HTTP header dedicated xtd-Accept.
The mime-type by default is application/xml.
The query sends the sub-program setups or the X3 object data in the required format.
The format of data sent by the call to a server script is free.
Application messages
The application messages are sent to three specific HTTP headers.
xtd-msg-error
Contains error messages
xtd-msg-warning
Contains warning messages
xtd-msg-info
Contains information messages
An X3 application error is processed as an exception
Exceptions
The X3 application errors and compilation/execution errors of server scripts are sent in the form of an HTTP error of code 600.
The JAVA exceptions are sent in the form of anHTTP error of code 500.
The body of the query contains a description (ContentType=text/plain) of the error which depends on the exception type.
In the case of an X3 error, the HTTP xtd-msg-error header contains error messages