Nous consommons des services web, ou des ressources web de façon plus générique, depuis des années, avant que n’apparaissent les fonctionnalités proposées par IBM :
- le client de web service basé sur Axis. Ce dernier permettait originellement l’appel de services SOAP, et désormais supporte les services REST
- les fonctions http embarquées dans SQL
Nous sommes nombreux à avoir utilisé et à continuer d’utiliser le produit HTTPAPI, implémentation open source RPG ILE du protocole HTTP réalisé par Scott Klement.
Aujourd’hui, comment transformer notre code basé sur HTTPAPI vers Axis ?
Prenons un cas simple, mais réel, d’un service utilisé par un client pour interroger une CRM dans le cloud Azur :
Appel :
GET https://XXXXXXXXXXX.azurewebsites.net/api/v1.0/customerbalance/FR03/410100
L’appel nécessite une authentification HTTP basique, et le serveur web utilise un certificat SSL basé sur une autorité Microsoft.
Valeur de retour :
Un zip du code dans sa version HTTPAPI et AXIS est téléchargeable ici. Globalement, la structure du programme change peu, et voici les principales modifications.
Programme de service
Utilisation du programme de service QSYSDIR/QAXIS10CC au lieu de HTTPAPIR4
HTTTPAPI utilise un répertoire de liage (HTTPAPI). Pour plus de simplicité de compilation avec AXIS, vous pouvez également créer un répertoire de liage, cela permet de compiler directement par CRTBNDPRG sans être contraint de compiler d’abord en module (CRTRPGMOD) puis de créer ensuite le programme par CRTPGM :
CRTBNDDIR BNDDIR(NB/AXIS)
ADDBNDDIRE BNDDIR(NB/AXIS) OBJ((QSYSDIR/QAXIS10CC))
Inclusion
Les prototypes à inclure sont donc différents :
HTTPAPI : /include qrpglesrc,httpapi_h
AXIS : /include /qibm/proddata/os/webservices/V1/client/include/Axis.rpgleinc
Trace
Indispensable pour la mise au point des programmes :
HTTPAPI : http_debug(*ON : ‘/home/nb/httpapi.log’) ;
AXIS : axiscAxisStartTrace( ‘/home/nb/axis.log’ : » ) ;
Entête de la requête
HTTPAPI permet de personnaliser l’entête de la requête HTTP via une procédure de callback, c’est-à-dire une procédure que vous fournissez et qui est appelé ultérieurement par HTTPAPI.
Inscription de la procédure dans HTTPAPI :
Corps de la procédure :
AXIS gère via des API la personnalisation de l’entête :
Encodage des paramètres sur l’URL
HTTPAPI fournit des procédures permettant d’encoder les valeurs à transmettre sur l’URL (échappement des blancs, caractères spéciaux, accentués …) :
AXIS ne fournit aucune fonctionnalité, mais on s’appuie directement sur SQL :
Sécurité
Dans notre cas, certificat publique, aucune action spécifique n’est nécessaire pour HTTPAPI.
Par contre, nous devons apporter quelques précisions à Axis pour activer le SSL. Ici on indique le magasin de certificat *SYSTEM et la capacité à ignorer les erreurs de certificat (périmé par exemple) :
Appel et résultat
HTTPAPI va stocker le résultat de l’appel dans un fichier sur l’IFS (à vous de fournir le nom), là où AXIS retourne un résultat en mémoire.
La valeur retournée est ici un flux XML que nous exploitons avec xml-into.
Pour HTTPAPI :
Pour AXIS :
Conclusions
Pourquoi passer de HTTPAPI à AXIS ?
HTTPAPI a été créé pour combler le manque de fonctionnalité HTTP de nos programmes RPG. IBM fournit et maintient AXIS, basé sur un produit Open Source Apache, et comble donc ce vide.
La transformation de l’un à l’autre se fait sans difficulté.
Maintenant, il existe une possibilité via SQL, qui fera l’objet d’un prochain billet.
Références :
https://www.scottklement.com/httpapi/
https://www-03.ibm.com/systems/resources/systems_i_software_iws_pdf_WebServicesClient_new.pdf
