Sending requests to the Web service and Authentication

 

Sending a request to a Web service is done by sending an HTTP request  accompanied by a Web form. Each Web service has a specific URL and some fields to transfer (this is sometimes optional) by sending these in a JSON in the variable actionParameters

 

Headers

 

You must send to each HTTP requests some headers with the following information in order to authenticate with the Web service:

---

prim-username

string

User of Web service: e.g.: PRIMWebService

---

prim-userkey

string

Web service Key

---

Accept

string

Value to use: application/json

---

 

Body

 

The body of the HTTP request  includes fields of the form, if applicable, to send to Web service, and must be in the following format:

---

actionParameters

json

Includes the fields defining the result returned by Web service

Possible value:

{
    "actionParameters":
    {
        ... Write here in JSON format the various fields that you want to send to Web service. This section is definded in each help page of the Web service
    }
}

If there is no mandatory field for the Web service, a blank body is sent with the HTTP query

 

Note

When you specify several fields in the same request, filters will be processed with a logical AND  (intersection of results)

 

---

 

HTTP Form sending method

 

HTTP requests must be sent using the POST method

 

---

 

General note

Data including fields sent to Web service must be in JSON format and valid. See RFC 8259

 

Sending a JSON to a Web service

---

Very important

1.The character set (charset) used for strings containing the values for properties in the JSON must be UTF-8.

2.The JSON sent to Web service must not include a line break (new line) character in string type values (text) for properties. These characters must  absolutely be removed or replaced before compilation of the JSON. And then, these characters should be put back in the JSON before it sent in order to perserve text formatting.

3.Accented or special characters must be  ou spéciaux shall be represented in the JSON by the corresponding Unicode character number in hexadecimal notation preceded by \u.

 

Ex.: Keyword : Employées

{
    "FilterWordTitle": "Employ\u00e9es"
}

Ex.: Processiong of new line characters contained in the JSON in PHP before it is sent to Web service

    $FilterCriteria = [];
    $FilterCriteria[] = [
        "type" => "Full",
        "cgrcod" => "REG",
        "cchcod" => "MTL",
        "SearchOption" => 1
    ];
    $FilterCriteria[] = [
        "type" => "Full",
        "cgrcod" => "REG",
        "cchcod" => "LGL",
        "SearchOption" => 1
    ];
    $language = "FR";
    $FilterDivision = 1;
    // Simulates the case where a user enters a line break (new line)
    $FilterWordTitle = "Denei\ngement";
    // Replaces the various line breaks with characters ###, #### and #####
    $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);
    // Puts back the line break in the JSON string
    $unsafeJSONJobsWebService = str_replace("#####", "\r\n", $jsonJobsWebService);
    $unsafeJSONJobsWebService = str_replace("####", "\r", $unsafeJSONJobsWebService);
    $unsafeJSONJobsWebService = str_replace("###", "\n", $unsafeJSONJobsWebService);

 

Ex.: Same example in 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;
    // Simulates the case where a user enters a line break (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
    };
    ...
    // Replace the various line breaks with characters ###, ####, #####
    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);
    // Puts back the line break in the JSON string
    string unsafeJSONJobs = jsonJobs.Replace("#####", @"\r\n");
    unsafeJSONJobs = unsafeJSONJobs.Replace("####", @"\r");
    unsafeJSONJobs = unsafeJSONJobs.Replace("###", @"\n");

 

Receiving a JSON from a Web service

---

Very important

1.The character set (charset) used for strings containing the values for properties in the JSON is UTF-8.

2.Fields returned by Web service with type string (text), especially the ones containing HTML code or a title, can include some line break characters (\r\n). Please note that these characters, when present in the JSON, must imperatively be removed or replaced in the string before decompiling. It is then necessary to put these characters back in order for the text in the field to be displayed correctly.

 

Thus, you have to do the previous steps in reverse order when you receive a JSON and use the following methods:

 

in PHP:

json_decode($output);

 

or in ASP.Net C#

JsonConvert.DeserializeObject<object>(output);

 

Example in PHP:

    $jsonStr = "{\"ClientDescription\":\"<p><img src=\\\"FSHCOD:35982\\\" style=\\\"width: 474px;\\\">\n Employ\u00e9es   </p>\"}";
    // Replaces the various line breaks with characters ###, ####, ##### in the JSON string
    $safeJsonStr = preg_replace("/\r\n/", "#####", $jsonStr);
    $safeJsonStr = preg_replace("/\r/", "####", $safeJsonStr);
    $safeJsonStr = preg_replace("/\n/", "###", $safeJsonStr);
    $json = json_decode($safeJsonStr);
    // Puts back the line breaks in the properties of the object with string type
    $json->ClientDescription = str_replace('#####', "\r\n", $json->ClientDescription);
    $json->ClientDescription = str_replace('####', "\r", $json->ClientDescription);
    $json->ClientDescription = str_replace('###', "\n", $json->ClientDescription);

 

Same example 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>""}";
    // Replaces the various line breaks with characters ###, ####, ##### in the JSON string
    string safeJsonStr = Regex.Replace(jsonStr, @"\r\n", "#####");
    safeJsonStr = Regex.Replace(safeJsonStr, @"\r", "####");
    safeJsonStr = Regex.Replace(safeJsonStr, @"\n", "###");
    GetOneJobData getOneJobData = JsonConvert.DeserializeObject<GetOneJobData>(safeJsonStr);
    // Puts back the line breaks in the properties of the string type object with string type
    getOneJobData.ClientDescription = getOneJobData.ClientDescription.Replace("#####", @"\r\n");
    getOneJobData.ClientDescription = getOneJobData.ClientDescription.Replace("####", @"\r");
    getOneJobData.ClientDescription = getOneJobData.ClientDescription.Replace("###", @"\n");