,

Retourner des documents grâce aux Web Services !

Vous êtes de plus en plus nombreux à utiliser IWS pour exposer des programmes (de service) ILE sous forme de service web ! Cette technique fonctionne bien : elle est simple, automatique, le code est écrit en RPG.

Mais utilisez vous toutes les possibilités fournies : XML ou JSON pour encapsuler les paramètres en sortie ?

De plus, nous sommes limités par le nombre de paramètres du code RPG :

  •  7 paramètres pour une procédure (SIC !!)
  • 256 paramètres pour un programme

 

Personnalisez vos services

Nous vous proposons aujourd’hui d’utiliser un type de media personnalisé en valeur de retour : vos services pourront retourner des documents de type XML, JSON, CSV, HTML, … en réalité tous les types usuels du web basés sur du texte.

 

Par exemple, la procédure suivante ramène les profils utilisateurs non système (la première lettre est différente de Q) et désactivés (une occasion de faire du ménage) :

Les paramètres :

  • data_LENGTH et data
    • longueur et valeur des données en sortie
  • httpStatus
    • permet le contrôle du code HTTP en retour par le programme RPG
    • un code 200 signifie OK et est celui généré automatiquement par l’outil. Un autre code connu : 404 NOT FOUND

 

Au déploiement du service vous devez indiquer certaines options :

On remarque :

  • HTTP response code output parameter -> httpStatus
  • Returned output media types -> application/xml

Cette dernière option signifie que la valeur de retour sera toujours un document XML

 

Exemple lors de l’appel depuis un navigateur :

Ici le navigateur se base sur le type indiqué pour le retour (application/xml) pour mettre en forme le résultat.

 

Encore plus !

Nous pouvons maintenant aller plus loin en rendant dynamique les types de données en sortie !

Par exemple, une procédure permettant de lire un fichier sur l’IFS dont le nom est transmis en paramètre, et de retourner son contenu :

Le nom du fichier à retourner est reçu dans le paramètre file.

Nous gérons dans le tableau httpHeaders() la valeur du type de contenu en retour via une entête HTTP Content-Type. Les valeurs usuelles sont listées ici : https://en.wikipedia.org/wiki/Media_type

Le type de contenu est défini en fonction de l’extension du fichier : application/xml pour tous les fichiers *.xml.

Si une extension n’est pas connu du programme, nous provoquons une erreur HTTP 406 NOT ACCEPTABLE.

De plus, si le fichier n’est pas trouvé, un code HTTP 404 NOT FOUND est généré.

 

Lors du déploiement, il est également nécessaire d’indiquer certaines options :

Principalement dans « Returned output media types » -> doit contenir la liste de tous les types de médias retournées par le programme. Une valeur qui ne serait pas présente ici sera interceptée par le serveur IWS et provoquera une erreur HTTP 500 (Internal Server Error) et aucune valeur ne sera retournée.

Les différentes valeurs sont séparées par des virgules :  application/xml, text/csv, text/html, text/plain.

Le swagger généré tient compte de ces informations pour une meilleur documentation et interopérabilité de vos services.

 

Lors des différents appels (les fichiers indiqués sur l’URL existent dans le répertoire /home/NB/ressources) :

 

Pour la gestion des cas d’erreur (extension non gérée ou fichier inexistant) :

 

Grâce à IWS, vos programmes RPG peuvent désormais facilement renvoyer tous types de documents, que le contenu soit statique (comme un fichier dans l’IFS) ou dynamique (calculé en live par votre programme). Et n’oubliez pas, DB2 offre de nombreuses possibilités (XML, JSON, accès à l’IFS …) qui sont donc directement utilisables en SQLRPGLE.

Prochaine étape : des fichiers binaires (image, pdf) !

/par