Services WEB

W-S  REST et paramètres

Lorsque vous déployez un programme ou une procédure, les paramètres peuvent être transmis de différentes manières

• 

  • *QUERY_PARAM

  • *PATH_PARAM

  • *FORM_PARAM

  • *COOKIE_PARAM

  • *HEADER_PARAM

  • *MATRIX_PARAM

  •  

    Ou « Wrap »

     

• Allowed input media types

  Cette option contrôle le type de données acceptées par le serveur

  • Le type de média envoyé par le client doit correspondre

     

    -> Valeur de « Content-Type » dans l'entête HTTP

     

    
    
    

    Dans le cas contraire, le serveur renvoie « HTTP 415 : Unsupported media type »

    
    

    Valeur	Comportement	Header HTTP supporté
    *ALL	Tout média accepté	Content-Type: */* Y compris application/x-www-form-urlencoded
    *XML	Uniquement flux XML	Content-Type: application/xml
    *JSON	Uniquement données JSON	Content-Type: application/json
    *XML_AND_JSON	Flux XML ou données JSON	Content-Type: application/xml Content-Type: application/json

• Les types

  • *JSON, *XML et *XML_AND_JSON

  • Correspondent aux usages applicatifs les plus courrants

• Le type *ALL

  • Permet de traiter une requête issue d'un formulaire HTTP La norme HTML indique dans ce cas que l'entête contient
    Content-Type:application/x-www-form-urlencoded

    N'est pas traité si *JSON ou *XML

  •  

    Attention : n'importe quelle autre valeur peut être transmise, le serveur essaiera de traiter la requête

     

• Returned output media types

  Cette option permet de régler le format de données disponible en sortie

  • De même, le type de données accepté et demandé par le client doit correspondre

    
    
    

    Accept: application/json ou application/xml

    
    

    Valeur	Comportement	Header HTTP supporté
    *XML	Uniquement flux XML	Aucun ou Accept: application/xml
    *JSON	Uniquement données JSON	Aucun ou Accept: application/json
    *XML_AND_JSON	Flux XML ou données JSON	Aucun (défaut = XML) ou Accept: application/xml Accept: application/json

• Pour tous les exemples suivants, nous utilisons la procédure ILE getClient avec les définitions suivantes

  
  

  

   

• La procédure est déployée avec les paramètres

  
  

  

   

• *QUERY_PARAM

  Ce mode correspond à  des paramètres transmis sur l'URL

  • Sous cette forme

    ?numcli=5&isactive=O&effet=2015-07-21

  • Déclaration du service

    
    

    
    

    

    
    

    C'est le nom défini dans la colonne « Identifier » qui doit être indiqué sur l'URL

    Il est possible d'indiquer des valeurs par défaut Si la valeur n'est pas transmise dans l'URL

• Trace HTTP requête
  
  

  GET

  http://<votre-ip>:10000/web/services/WSRESTTESTQUERY/getClient?numcli=5&isactiv e=O&effet=2015-07-21 HTTP/1.1

  Accept-Encoding: gzip,deflate Content-Type: application/json Host: <votre-ip>:10000

  Connection: Keep-Alive

  User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

  
  

• Trace HTTP réponse
  
  

  HTTP/1.1 200 OK

  Date: Thu, 16 Jul 2015 16:59:00 GMT

  Server: Apache

  X-Powered-By: IBM i Content-Length: 118 Connection: close

  Content-Type: application/json

  
  

  {"DEBUG":"numcli => 5, isActive => O, effet => 2015-07- 21","CLIENT":{"ID":10,"NOM":"Test NOM","PRENOM":"Test PRENOM"}}

•  

• *PATH_PARAM

  Dans ce mode les paramètres ne sont pas transmis en paramètres de l'URL, mais constituent directement l'URL

  • Sous cette forme

    /15/O/2015-07-21

  • Déclaration du service

    
    

    

    
    

    

• Il faut ici

  • Indiquer un « path template » c'est-à -dire un masque d'URL contenant des variables

  • Ces noms de variables sont les noms à  indiquer dans la colonne

    « Identifier » pour faire le lien avec les paramètres réels

• Restrictions

  • L'utilisation de valeurs par défaut est impossible ici : c'est le rang du paramètre dans l'URL qui importe

     

• Trace HTTP requête
  
  

  GET http://<votre-ip>:10000/web/services/WSRESTTESTPATH/getClient/15/O/2015-07-21 HTTP/1.1

  Accept-Encoding: gzip,deflate Content-Type: application/json Host: <votre-ip>:10000

  Connection: Keep-Alive

  User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

  
  

• Trace HTTP réponse
  
  

  HTTP/1.1 200 OK

  Date: Thu, 16 Jul 2015 17:09:37 GMT

  Server: Apache

  X-Powered-By: IBM i Content-Length: 119 Connection: close

  Content-Type: application/json

  
  

  {"DEBUG":"numcli => 15, isActive => O, effet => 2015-07- 21","CLIENT":{"ID":10,"NOM":"Test NOM","PRENOM":"Test PRENOM"}}

• *FORM_PARAM

  Ce mode correspond à  la transmission des paramètres sous forme d'un formulaire HTTP

  • Les données sont transmises dans la requête sous la forme

  • numcli=15&isactive=O&effet=2015-07-21

  • Déclaration du service

    
    

    

    
    

  • Méthodes acceptées

    POST et PUT uniquement

• Les noms indiqués dans la colonne « Identifier » doivent correspondre aux noms des valeurs envoyées par le formulaire

   

• Exemple via un formulaire HTML

  <form action="http://<votre-ip>:10000/web/services/WSRESTTESTFORM2/" enctype='application/json' method="POST">

  N° client:<br>
  <input type="text" name="numcli"><br> Actif:<br>
  <input type="text" name="isactive"><br> Date d'effet:<br>
  <input type="text" name="effet">

  <input type="submit" value="Submit">

  </form>

  
  

  

   

• Trace HTTP requête

  POST

  http://<votre-ip>:10000/web/services/WSRESTTESTFORM/?numcli=15&isactive=O&effet=2015-07-21 HTTP/1.1

  Accept-Encoding: gzip,deflate

  Content-Type: application/x-www-form-urlencoded Content-Length: 0

  Host: <votre-ip>:10000

  Connection: Keep-Alive

  User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

  
  

• Trace HTTP réponse

  HTTP/1.1 200 OK

  Date: Thu, 16 Jul 2015 17:23:22 GMT

  Server: Apache

  X-Powered-By: IBM i Content-Length: 107 Connection: close

  Content-Type: application/json

  
  

  {"DEBUG":"numcli => 15, isActive => O, effet => 215-07- 21","CLIENT":{"ID":10,"NOM":"Test NOM","PRENOM":"Test PRENOM"}}

   

• Si vous utilisez des formulaires HTML

  • Le navigateur indique dans l'entête HTTP

    Content-Type: application/x-www-form-urlencoded

  • Cette requête n'est traitée que si votre service est déployé avec

    Allowed input media type = *ALL

    
    

    

    
    

  • Dans le cas contraire, votre entête HTTP doit contenir

    Content-Type: application/xml

    Ou

    Content-Type: application/json

  • 
    

    Vous obtiendrez sinon : HTTP 415 Unsupported Media Type

• Pour contrôler l'entête

  • Dans une page HTML

    Vous devez utiliser JavaScript pour créer dynamiquement la requête HTTP

  • Dans vos applications

    Par programmation, en fonction des langages et outils
• *HEADER_PARAM

  Ce mode correspond à  des paramètres transmis dans l'entête
  

  • Sous cette forme

    nom: valeur

  • Ils n'apparaissent pas dans l'URL ni dans le corps de la requête

  • Déclaration du service

    
    

    

    C'est le nom défini dans la colonne « Identifier » qui doit être indiqué Il est possible d'indiquer des valeurs par défaut

    Si la valeur n'est pas transmise dans l'entête

• Trace HTTP requête
  
  

  GET http://<votre-ip>:10000/web/services/WSRESTTESTHEADER/ HTTP/1.1 Accept-Encoding: gzip,deflate

  numcli: 15 isactive: O effet: 2015-07-21

  Content-Type: application/json Host: <votre-ip>:10000

  Connection: Keep-Alive

  User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

  
  

• Trace HTTP réponse
  
  

  HTTP/1.1 200 OK

  Date: Fri, 17 Jul 2015 15:38:57 GMT

  Server: Apache

  X-Powered-By: IBM i Content-Length: 119 Connection: close

  Content-Type: application/json

  
  

  {"DEBUG":"numcli => 15, isActive => O, effet => 2015-07- 21","CLIENT":{"ID":10,"NOM":"Test NOM","PRENOM":"Test PRENOM"}}

• *MATRIX_PARAM

  Ce mode correspond à  des paramètres transmis sur l'URL

  • Sous la forme

    ;numcli=15;isactive=O;effet=2015-07-21

  • Déclaration du service

    
    

    

    C'est le nom défini dans la colonne « Identifier » qui doit être indiqué

    Il est possible d'indiquer des valeurs par défaut, si la valeur n'est pas transmise

     

• Matrix URI

  • Ce mode est peu utilisé

  • Il présente toutefois certains avantages

    Les paramètres Matrix peuvent être n'importe où dans l'URL, pas obligatoirement à la fin

    Un paramètre peur avoir plusieurs valeurs (tableau)

    param=val1,val2

  • Ils sont actuellement supportés par peu d'outils

  • 
    Plus d'informations

    http://www.w3.org/DesignIssues/MatrixURIs.html

• Trace HTTP requête
  
  

  GET

  http://<votre-ip>:10000/web/services/WSRESTTESTMATRIX/;numcli=15;isactive=O;effet=20 15-07-21 HTTP/1.1

  Accept-Encoding: gzip,deflate Content-Type: application/json Host: <votre-ip>:10000

  Connection: Keep-Alive

  User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

  
  

• Trace HTTP réponse
  
  

  HTTP/1.1 200 OK

  Date: Fri, 17 Jul 2015 15:45:07 GMT

  Server: Apache

  X-Powered-By: IBM i Content-Length: 119 Connection: close

  Content-Type: application/json

  
  

  {"DEBUG":"numcli => 15, isActive => O, effet => 2015-07- 21","CLIENT":{"ID":10,"NOM":"Test NOM","PRENOM":"Test PRENOM"}}

• Le mode WRAP

  Ce mode peut être utilisé pour l'ensemble des paramètres (Wrap Input parameter)

  • L'ensemble des paramètres est alors enveloppé(wrap) dans une structure, à  transmettre avec la requête

    En XML ou en JSON

  • Seuls les méthodes POST et PUT sont alors supportées

• Exemple sur getClient

  • En JSON
    
    

    POST http://<votre-ip>:10000/web/services/WSRESTTEST/WSRESTTEST/GETCLIENT HTTP/1.1

    Accept-Encoding: gzip,deflate Content-Type: application/json Content-Length: 73

    Host: <votre-ip>:10000

    Connection: Keep-Alive

    User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

    
    

    {

    "NUMCLI": "5",

    "ISACTIVE": "O",

    "EFFET": "2015-07-15"

    }

    
    

  • Il n'est pas nécessaire de donner un nom à  la structure JSON

  • Les noms des valeurs contenues dans la structure JSON doivent correspondre aux paramètres de la procédure/programme

  • En XML

    POST http://<votre-ip>:10000/web/services/WSRESTTEST/WSRESTTEST/GETCLIENT HTTP/1.1

    Accept-Encoding: gzip,deflate Content-Type: application/xml Content-Length: 111

    Host: <votre-ip>:10000

    Connection: Keep-Alive

    User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

    
    

    <getclientInput>

    <NUMCLI>5</NUMCLI>

    <ISACTIVE>O</ISACTIVE>

    <EFFET>2015-07-15</EFFET>

    </getclientInput>

    
    

  • XML impose de donner un nom à  la racine

    Nom de la procédure ILE en minuscule + « Input », modifiable en TR2/TR8
    

  • Le nom des balises XML doivent correspondre aux noms des paramètres de la procédure/programme

     

  Il est implicite dès que l'on a une structure en entrée
  
  
  

  Dot not Wrap Input parameter : Chaque paramètre est transmis suivant une source (*PATH_PARAM, *QUERY_PARAM, ...)
  sauf la structure qui a comme source *NONE :

Exemple avec cette procédure

 

o ON peut, malgré tout, “envelopper” l'ensemble des paramètres avec :

 

• Appel « Wrap » en XML

  
  

  POST http://<votre-ip>:10000/web/services/WSRESTTEST/WSRESTTEST/PUTCLIENT HTTP/1.1

  Accept-Encoding: gzip,deflate Content-Type: application/xml Content-Length: 161

  Host: <votre-ip>:10000

  Connection: Keep-Alive

  User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

  
  

  <putclientInput>

  <CLIENT>

  <ID>25</ID>

  <NOM>Test NOM</NOM>

  <PRENOM>Test PRENOM</PRENOM>

  </CLIENT>

  <ACTION>CREER</ACTION>

  </putclientInput>

• Appel « Wrap » en JSON

  
  

  POST http://<votre-ip>:10000/web/services/WSRESTTEST/WSRESTTEST/PUTCLIENT HTTP/1.1

  Accept-Encoding: gzip,deflate Content-Type: application/json Content-Length: 137

  Host: <votre-ip>:10000

  Connection: Keep-Alive

  User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

  
  

  {

  "CLIENT":

  {

  "ID": "25",

  "NOM": "Test NOM", "PRENOM": "Test PRENOM"

  },

  "ACTION": "CREER"

  }

• ---

• Pensez que tout cela s'appuie sur PCML qui, historiquement,ne reconnait pas :

•   • les dates (cela n'est plus vrai en pcml6*)

    • les heures

    • les timestamp (cela n'est plus vrai en pcml6*)

    • les pointeurs

    • les zones à taille variable (cela n'est plus vrai en pcml7 **)

    • les zones binaires sur 1 octet et 8 octets (seulement 2 et 4)
  
  

    • et qui limite le passage de paramètres par valeur aux entiers sur 4 octets.
  

   

  Le nombre de paramètres est aussi limité, à :

   

    • 32 pour un *PGM

    • 7 pour un *SRVPGM !
  
  

•  

• Exemple avec ce programme attendant une date en entrée (p1) et retournant une date (p2)

• 

• Une fois déployé, testons :

• 

•  

  Exemple pour les timestamp,ce programme

   
  
  exposé en tant que web service retournant du XML affiche :
  

  
  EN JSON :

  

Autres remarques pour les paramètres OUTPUT

• Un des paramètres , de type INT(10) peut contenir le HTTPSatus (le code)
  
  
  Il n'est alors PAS retourné avec les données

et s'il signale une erreur (> 400) aucune donnée n'est retournée avant la TR2/TR8

 

• Un des paramètres , Tableau de type CHAR() peut contenir les HTTPheader (les entêtes)
  
  
  Chaque occurrence significative contient une entête sous la forme nom:valeur
  

   

  Ce paramètre n'est alors PAS retourné avec les données

• Extrait du code RPG
  

Nouveautés TR2/TR8

Les noms de structure sont modifiables (Important pour le XML c'est le nom "racine")

On peut préciser les status HTTP et indiquer un message d'erreur significatif

On peut forcer une entête HTTP (en tant que constante)

ET surtout, retourner un code erreur n'empèche plus de retourner des données

  exemple avec ce pgm

une date valide

une date invalide

Attention p3 doit être formaté comme indiqué ici

Sinon

Cela risque de sembler incohérent au client