Web services REST

Introduction

Le serveur XTEND met à disposition des développeurs d'applications AJAX deux types de web services REST qui peuvent être invoqués directement à partir du navigateur web par une requête HTTP.

Appel d'un web service SOAP X3 via une interface XTEND
Appel d'un script serveur

Ces services ne sont accessibles qu'aux applications XTEND.

Le moteur ne prend en compte que les requêtes REST qui ont une session XTEND associée via le cookie (ou le paramètre de l'URL) JSESSIONID.

Les services REST XTEND ne sont disponibles que sur le serveur XTEND.

Ils 'encapsulent' l'appel des web services SOAP X3.

Les structures des données REST échangées pour le passage des paramètres (clés et données) et le retour du résultat (données et messages) sont identiques à celles des services SOAP.

Seul le protocole d'échange avec le client est différent.

Rappel sur les web services SOAP X3

Ce paragraphe présente de manière générale les Web services SOAP X3 disponibles ainsi que les structures de données associées.

La connaissance des web service SOAP X3 est indispensable pour utiliser les services REST d'XTEND.

Paramètres d'appel

Paramètres obligatoires

Le contexte d'appel CAdxCallContext callContext
Contient les information de login X3 et sur le pool de connexion qui va traiter la requête
Le nom de publication du web service String publicName défini lors de la publication

public CAdxCallContext {
    //Code langue X3
    String codeLang;
    //Code utilisateur X3
    String codeUser;
    //Mot de passe X3
    String password;
    //Alias du pool de connexion sur le serveur de web services
    String poolAlias;
    //Paramètres de configuration (query string)
    String requestConfig;
}

Les paramètre adxwss.optreturn=JSON/XML de la query string requestConfig indique le type de résultat (XML par défaut).

Le serveur de web service détecte automatiquement le format XML ou JSON en entrée.

Options JSON

Le format JSON propose des options pour filtrer les données renvoyées par le web service.

Les options sont passées :

soit dans la query string requestConfig via le paramètre adxwss.optjson
requestConfig=adxwss.optreturn=JSON&adxwss.optjson={"OPTIONS":"noGoups"}
soit dans les paramètres JSON de l'objet ou du sous programme via le champ "_JSONOPT"
Voir exemple des paramètres d'appel JSON

L'option JSON est un objet JSON qui comporte au moins un des champs ci-dessous.
{
    OPTIONS:["nolabels","noclobs","nogroups","norows"],
    LANG:"FRA",
    EXCLUDEGRP:["GRP1","GRP2"],
    INCLUDEGRP:["GRP1","GRP2"],
    EXCLUDEFLD:["FLD1","FLD2"],
    INCLUDEFLD:["FLD1","FLD2"]
}

OPTIONS

noGroups
Pas de groupes de publication en retour
Chaque paramètre du sous-programme ou champ de l'objet est un tableau de String

noRows
Pas de lignes dans les tableaux avec dim>1
Chaque paramètre du sous-programme ou champ de l'objet est un tableau de String

noLabels
Pas de labels pour les menus locaux

noClobs
Les champs clob ne sont pas renvoyés

Le champs OPTION accepte soit un tableau de paramètre soit un seul paramètre (String)

EXCLUDEGRP
Exclut les groupes mentionnés

INCLUDEGRP
Inclut les groupes contenus mentionnés

EXCLUDEFLD
Exclut les champs mentionnés

INCLUDEFLD
Inclut les champs mentionnés

Les champs INCLUDE* et EXCLUDE* acceptent soit un tableau de Strings soit un String

Paramètres clé d'objet X3

Le paramètre CAdxParamKeyValue objectKeys pour les méthodes des objets X3 qui nécessitent des clés (Read/Query...).

Il s'agit d'un tableau codeChamp/valeur.

public class CAdxParamKeyValue{
private String key;
private String value;
}

Paramètres données

Le paramètre String objectXml pour un objet X3 ou String inputXml contient les données de l'objet ou les paramètre du sous-programme au format XML ou JSON.

Le format JSON a été ajouté pour les besoins des application AJAX.

Exemple de format d'appel du web service de login AXTDLOGIN du site ASAMPLE.

Param JSON

Option JSON dans les paramètres d'appel : nogroups, norows
{
    _JSONOPT:{OPTIONS:["nogroups", "norows"]},
    AXPARCOD:["SITCOD", "USRLANG"],
    AXPARVAL:["FDBTEST", "FRA"],
    AXUSERCODE:"DIS001",
    AXPWD:"adonix"
}

Param XML

<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>

Structure paramètre données sous-programme

Les champs <FLD NAME="FieldName"> représentent les paramètres du sous-programme et sont rattachés au groupe de publication

Les groupes de publications sont définis dans la fiche Web service associé à la fiche du sous-programme.

Ils sont représentés par les noeuds <GRP ID="IdGroup"> pour les paramètres de dimension 1 et <TAB ID="IdGroup"> pour les paramètres de dimension > 1.

Le noeuds <LIN> regroupe les champs d'un même groupe tableau ayant le même indexe.

Les paramètres JSON reprennent la même structure mais on n'est pas obligé d'utiliser les groupes de publication.

Sous Programme XML

<PARAM>
    <GRP ID=’GRP1’>
        <FLD NAME=’CHAMP’>Valeur</FLD>
    </GRP>
    <TAB ID=’GRP2’>
        <LIN>
            <FLD NAME=’CHAMP1’>Valeur1</FLD>
            <FLD NAME=’CHAMP2’>Valeur1</FLD>
        </LIN>
        <LIN>
            <FLD NAME=’CHAMP1’>Valeur1</FLD>
            <FLD NAME=’CHAMP2’>Valeur2</FLD>
        </LIN>
    </TAB>
</PARAM>

Sous Programme JSON

/*--- Sans les groupes ---*/
{
    CHAMP:"Valeur",
    CHAMP1:["Valeur1","Valeur2"],
    CHAMP2:["Valeur1","Valeur2"]
}
/*--- Avec les groupes ---*/
{
    GRP1:{
        CHAMP:"Valeur"
    },
    GRP2:[
        {
            CHAMP1:"Valeur1",
            CHAMP2:"Valeur1"
        },
        {
            CHAMP1:"Valeur2",
            CHAMP2:"Valeur2"
        }
    ]
}

Structure paramètre données Objet X3

Même structure que les sous-programme mais les noms des groupes sont codés en fonction de la place du bloc dans l'écran.

En mode JSON il n'est pas obligatoire de spécifier les noms des groupes.

Il est laissé au développeur l'initiative de spécifier le nom du groupe dans le cas où il souhaite utiliser un champ de l'objet X3 dont le nom seul ne permet pas de l'identifier.

On peut avoir plusieurs champs de même nom dans un objet X3.

Exemple pour la commande SOH
SOH4_1 (lignes de la commande) correspond au 1er bloc du 4eme écran

Objet XML

Objet JSON

{
    BPCORD:"DIS001",
    SOHTYP:"WEB",
    SALFCY:"ASN",
    STOFCY:"ASN",
    ITMREF:["CUB100","CD100"],
    ITMREF:["50","10"]
}

Services

/*--------------- Appel d'un SOUS-PROGRAMME ---------------*/
public CAdxResultXml run(
    CAdxCallContext callContext,
    String publicName,
    String inputXml) throws Exception;

/*--------------- Appel d'un sous OBJET X3---------------*/
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;
}

Résultat

L'appel d'un web service renvoie toujours un objet résultat CAdxResultXml qui contient :

les données de l'objet ou paramètres du sous-programme au format XML ou JSON
String resultXml
les messages application de type erreur, warning ou information
CAdxMessage messages
des information techniques sur l'exécution du sous programme
CAdxTechnicalInfos technicalInfos

Le erreurs applicatives X3 ne sont pas renvoyées comme des exceptions.

Le format JSON ignore les paramètre de type BLOB qui contiennent du binaire.

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":Erreur
    public String type;
}

Exemple de résultat suite à l'appel du web service de login AXTDLOGIN du site ASAMPLE.

Résultat JSON

Options JSON : norows et 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"]
}

Résultat XML

<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>

Web services REST XTEND

Principe de fonctionnement

Voici les différentes étapes de traitement d'une requête REST:

1. Réception de la requête HTTP par le servlet ajax du serveur XTEND

2. Recherche de la session XTEND associée

Via le cookie ou le paramètre de la requête JSESSIONID
-> Erreur si aucune session n'a été trouvée

3. Analyse de l'URL pour en déduire les coordonnées du site XTEND et le type de service

Plusieurs sites peuvent être ouverts simultanément par une session XTEND
-> Erreur si site non trouvé

4. Exécution du script serveur ou appel du web service SOAP X3

Traitement du script serveur

1. Lecture du chemin d'accès dans l'URL

2. Lecture et compilation du script JavaScript

3. Exécution du script

Le script a la capacité d'accéder aux données de la session et d'appeler des web services SOAP X3
L'instruction print du script est utilisée pour renvoyer la réponse (XML, JSON, HTML...)

Traitement de l'appel du web service SOAP X3

1. Lecture du code de l'interface XTEND dans l'URL

L'interface fait référence à un web service SOAP
-> Erreur si interface non déclarée dans le site

2. Constitution des paramètres d'appel

Les données XML ou JSON sont lues dans le corps de la requête
Les clés sont lues dans la 'Query String'
Le type de résultat demandé XML ou JSON est lu dans le header HTTP xtd-accept

3. Constitution du contexte d'appel du web service SOAP

Le point d'entrée (URL) est donné par le site XTEND (Pool web service du site ou de l'interface)
Le code utilisateur X3, Mot de passe en langue sont donné par la session XTEND

4. Appel du web service SOAP

5. Constitution du résultat

Les messages ont transmis dans le header HTTP
xtd-msg-error, xtd-msg-warning,xtd-msg-info
Les données XML/JSON renvoyées par le web service SOAP sont transmises sans modification dans le corps de la requête

Format de l'URL

http://host:port/xtend/ajax/x3sol/x3folder/xtdsite/type/id[/méthode][?Paramètres]

Méthode HTTP POST ou GET

x3sol
Code solution X3

x3folder
Code dossier X3

xtdsite
Code site XTEND

type
INT pour l'appel d'une interface XTEND
SCRIPT pour l'appel d'un script server XTEND

id
    Code de l'interface
    ou
    Chemin d'accès du script par rapport au répertoire des scripts serveur du site XTEND

méthode
Code de la méthode de l'objet X3
QUERY, R Read, S Save, M Modify,D Delete

Paramètres
Query string qui peut contenir:

Les champs clés d'un objet X3
Les paramètres d'une liste gauche
Les options JSON via la clé _JSONOPT si elles ne sont pas passées dans les paramètres données

Exemples

Script
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/SCRIPT/ajaxTest1.js

Sous-programme
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

Liste gauche objet X3
http://host/xtend/ajax/SOLPAIE/PAIE/FDBTEST/INT/OBJAYZ/QUERY?_COUNT=10&FRMCOD=09*
&_JSONOPT=%7B%22OPTIONS%22%5B%22nogroups%22%7D

Envoie des données

Les paramètres de type données autre que ceux de la query string sont passés dans le corps de la requête HTTP.

Le format des paramètres d'appel d'une interface XTEND sont donnés par le ContentType de la requête HTTP:

application/json
La structure des données doit être conforme aux format attendu
application/xml
Les données XML doivent être conforme aux format attendu
application/x-www-form-urlencoded
Dans ce cas on considère que la liste des champs/valeurs constitue un objet JSON conforme au format attendu

Le ContentType par défaut est application/json.

Le format des données pour l'appel d'un script serveur est obligatoirement application/json.

Résultat

Lors de l'appel d'une interface XTEND on peut demander un format de retour XML (application/xml) ou JSON (application/json) en valorisant le Header HTTP dédié xtd-Accept.

Le mime-type par défaut est application/xml.

La requête renvoie les paramètres du sous-programme ou les données de l'objet X3 au format demandé.

Le format des données renvoyé par l'appel d'un script serveur est libre.

Messages applicatifs

Les messages applicatifs sont renvoyés dans trois headers HTTP spécifiques.

xtd-msg-error

Contient les messages d'erreur

xtd-msg-warning

Contient les messages warning

xtd-msg-info

Contient les messages d'information

Une erreur applicative X3 est traitée comme une exception

Exceptions

Les erreurs applicatives X3 et erreurs de compilation/exécution des scripts serveur sont renvoyées sous le forme d'une erreurHTTP de code 600.

Les exception JAVA sont renvoyées sous le forme d'une erreur HTTP de code 500.

Le corps de la requête contient une description (ContentType=text/plain) de l'erreur qui dépend du type d'exception.

Dans le cas d'une erreur X3 le header HTTP xtd-msg-error contient les messages d'erreur

Web services REST

Introduction

Rappel sur les web services SOAP X3

Paramètres d'appel

Paramètres obligatoires

Options JSON

OPTIONS

Paramètres clé d'objet X3

Paramètres données

Structure paramètre données sous-programme

Structure paramètre données Objet X3

Services

Résultat

Web services REST XTEND

Principe de fonctionnement

Traitement du script serveur

Traitement de l'appel du web service SOAP X3

Format de l'URL

Exemples

Envoie des données

Résultat

Messages applicatifs

xtd-msg-error

xtd-msg-warning

xtd-msg-info

Exceptions

Ces informations vous ont-elles été utiles ?

Nous en sommes désolés.

Vous souhaitez nous en dire plus ?

Parfait !

Liens du site

Liens Sage

Infos page

Media Sage