Envoi des requêtes au service Web et authentification

 

L'envoi d'une requête à un service Web se fait en envoyant une requête HTTP accompagnée d'un formulaire Web. Chaque service Web a un URL spécifique et des champs à passer (parfois c'est facultatif) en envoyant ceux-ci dans un JSON dans la variable actionParameters

 

Entêtes (headers)

 

Il faut envoyer à chaque requête HTTP des entêtes avec les renseignements suivants pour s'authentifier auprès du service Web:

---

prim-username

string

Utilisateur du service Web : par ex. : PRIMWebService

---

prim-userkey

string

Clé du service Web

---

Accept

string

Valeur à utiliser : application/json

---

 

Corps (Body)

 

Le corps de la requête HTTP contient les champs du formulaire, s'il y a lieu, à envoyer au service Web et doit être de la forme suivante :

---

actionParameters

json

Contient les champs qui définissent le résultat retourné par le service Web

Valeur possible:

{
    "actionParameters":
    {
        ... écrire ici au format JSON les différents champs qu'on veut envoyer au service web. Cette section est définie dans chaque page d'aide du service web
    }
}

Si aucun champ n'est obligatoire pour le service Web, on envoie alors un corps vide avec la requête HTTP

 

Note

Lorsque vous spécifiez plusieurs champs dans la même requête, les filtres sont traités avec un ET logique (intersection des résultats)

 

---

 

Méthode d'envoi du formulaire HTTP

 

Les requêtes HTTP doivent être envoyées avec la méthode POST

 

---

 

Remarque générale

Les données contenant les champs envoyés au service web doit être au format JSON et être valide. Voir la RFC 8259

 

Envoi d'un JSON à un service web

---

Très important

1.Le jeu de caractères (charset) employé pour les string contenant les valeurs des propriétés dans le JSON doit être le UTF-8.

2.Le JSON envoyé au service Web ne doit pas contenir de retour à ligne (new line) dans les valeurs de type string (texte) des propriétés. Il faut impérativement enlever ou remplacer ces caractères avant de compiler le JSON. Et il faut ensuite remettre ces caractères dans le JSON avant de l'envoyer afin de préserver le formatage du texte.

3.Les caractères accentués ou spéciaux doivent être représentés dans le JSON par le numéro du caractère Unicode correspondant en notation hexadécimale précédé de \u.

 

Ex. : Mot-clé : Employées

{
    "FilterWordTitle": "Employ\u00e9es"
}

Ex. : Traitement des retours à la ligne contenu dans le JSON en PHP avant de l'envoyer au service Web

    $FilterCriteria = [];
    $FilterCriteria[] = [
        "type" => "Full",
        "cgrcod" => "REG",
        "cchcod" => "MTL",
        "SearchOption" => 1
    ];
    $FilterCriteria[] = [
        "type" => "Full",
        "cgrcod" => "REG",
        "cchcod" => "LGL",
        "SearchOption" => 1
    ];
    $language = "FR";
    $FilterDivision = 1;
    // Simule le cas où un utilisateur entre un retour à la ligne (new line)
    $FilterWordTitle = "Denei\ngement";
    // Remplace les différents retours à la ligne par les caractères ###, #### et #####
    $safeFilterWordTitle = preg_replace("/\r\n/", "#####", $FilterWordTitle);
    $safeFilterWordTitle = preg_replace("/\r/", "####", $safeFilterWordTitle);
    $safeFilterWordTitle = preg_replace("/\n/", "###", $safeFilterWordTitle);
    $jobsWebService = [
        "Language" => $language,
        "FilterDivision" => $FilterDivision,
        ...
        "FilterCriteria" => $FilterCriteria,
        ...
        "FilterWordTitle" => $safeFilterWordTitle,
    ];
    $jsonJobsWebService = json_encode($jobsWebService);
    // Remets les retours à la ligne dans la string du JSON
    $unsafeJSONJobsWebService = str_replace("#####", "\r\n", $jsonJobsWebService);
    $unsafeJSONJobsWebService = str_replace("####", "\r", $unsafeJSONJobsWebService);
    $unsafeJSONJobsWebService = str_replace("###", "\n", $unsafeJSONJobsWebService);

 

Ex.: Même exemple en ASP.NET C#

using Newtonsoft.Json;
using System.Text.RegularExpressions;
...
    public class Criteria
    {
        public string type { get; set; }
        public string cgrcod { get; set; } = null;
        public string cchcod { get; set; } = null;
        public int SearchOptions { get; set; }
    }
    ...
    public class JobsParameters
    {
        public string Language { get; set; } = null;
        public int? FilterDivision { get; set; } = null;
        ...
        public Criteria[] FilterCriteria { get; set; } = null;
        ...
        public string FilterWordTitle { get; set; } = null;
    }
    ...
    string language = "FR";
    int filterDivision = 1;
    // Simule le cas où un utilisateur entre un retour à la ligne (new line)
    string filterWordTitle = "Dénei\ngement";
    Criteria[] filterCriteria = new Criteria[2];
    filterCriteria[0] = new Criteria
    {
        type = "Full",
        cgrcod = "REG",
        cchcod = "MTL",
        SearchOptions = 1
    };
    filterCriteria[1] = new Criteria
    {
        type = "Full",
        cgrcod = "REG",
        cchcod = "LGL",
        SearchOptions = 1
    };
    ...
    // Remplace les différents retours à la ligne par ###, ####, #####
    string safeFilterWordTitle = Regex.Replace(filterWordTitle, @"\r\n", "#####");
    safeFilterWordTitle = Regex.Replace(safeFilterWordTitle, @"\r", "####");
    safeFilterWordTitle = Regex.Replace(safeFilterWordTitle, @"\n", "###");
    JobsParameters jobsParameters = new JobsParameters{
        Language = language,
        FilterDivision = filterDivision,
        ...
        FilterCriteria = filterCriteria,
        ...
        FilterWordTitle = safeFilterWordTitle,
        ...
    };
    string jsonJobs = JsonConvert.SerializeObject(jobsParameters);
    // Remets les retours à la ligne dans la string du JSON
    string unsafeJSONJobs = jsonJobs.Replace("#####", @"\r\n");
    unsafeJSONJobs = unsafeJSONJobs.Replace("####", @"\r");
    unsafeJSONJobs = unsafeJSONJobs.Replace("###", @"\n");

 

Réception d'un JSON provenant d'un service Web

---

Très important

1.Le jeu de caractères (charset) utilisé pour le string dans le JSON est l'UTF-8.

2.Les champs retournés par le service Web et ayant le type string (texte), notamment ceux contenant du code HTML ou un titre, peuvent inclure des caractères de retour à la ligne (\r\n). Notez que ces caractères, lorsque présents dans le JSON, doivent impérativement être enlevés ou remplacés dans la string avant de la décompiler. Et il faut ensuite remettre ces caractères pour afficher correctement le texte du champ.

 

Ainsi, il faut faire les étapes précédentes dans l'ordre inverse quand on reçoit un JSON et qu'on utilise les méthodes suivantes :

 

en PHP:

json_decode($output);

 

ou en ASP.Net C#

JsonConvert.DeserializeObject<object>(output);

 

Exemple en PHP:

    $jsonStr = "{\"ClientDescription\":\"<p><img src=\\\"FSHCOD:35982\\\" style=\\\"width: 474px;\\\">\n Employ\u00e9es   </p>\"}";
    // Remplace les retours à la ligne par ###, ####, ##### dans la string du JSON
    $safeJsonStr = preg_replace("/\r\n/", "#####", $jsonStr);
    $safeJsonStr = preg_replace("/\r/", "####", $safeJsonStr);
    $safeJsonStr = preg_replace("/\n/", "###", $safeJsonStr);
    $json = json_decode($safeJsonStr);
    // Remets les retours à la ligne dans les propriétés de l'objet ayant le type string
    $json->ClientDescription = str_replace('#####', "\r\n", $json->ClientDescription);
    $json->ClientDescription = str_replace('####', "\r", $json->ClientDescription);
    $json->ClientDescription = str_replace('###', "\n", $json->ClientDescription);

 

Même exemple en ASP.NET C#:

using Newtonsoft.Json;
using System.Text.RegularExpressions;
...
    public class GetOneJobData
    {
        public string ClientDescription { get; set; }
    }
...
    string jsonStr = "{\"ClientDescription\":\"<p><img src=\\\"FSHCOD:35982\\\" style=\\\"width: 474px;\\\">\\n Employ\u00e9es    </p>\"}";
    ou
    string jsonStr =  @"{""ClientDescription"":""<p><img src=\""FSHCOD:35982\"" style=\""width: 474px;\"">\n Employ\u00e9es   </p>""}";
    // Remplace les retours à la ligne par ###, ####, ##### dans la string du JSON
    string safeJsonStr = Regex.Replace(jsonStr, @"\r\n", "#####");
    safeJsonStr = Regex.Replace(safeJsonStr, @"\r", "####");
    safeJsonStr = Regex.Replace(safeJsonStr, @"\n", "###");
    GetOneJobData getOneJobData = JsonConvert.DeserializeObject<GetOneJobData>(safeJsonStr);
    // Remets les retours à la ligne dans les propriété de l'objet ayant le type string
    getOneJobData.ClientDescription = getOneJobData.ClientDescription.Replace("#####", @"\r\n");
    getOneJobData.ClientDescription = getOneJobData.ClientDescription.Replace("####", @"\r");
    getOneJobData.ClientDescription = getOneJobData.ClientDescription.Replace("###", @"\n");