Mise à jour des données

Certaines APIs permettent la mise à jour des données via des méthodes dédiées.
Il est important de comprendre les principes de mise à jour pour éviter des erreurs ou des comportements inattendus.

Principes de mise à jour

Principe 1

La méthode POST est utilisée.
Les données sont transmises dans le corps de la requête.

Principe 2

Il vous sera toujours demandé de renseigner une donnée (ou plusieurs) permettant d'identifier de manière unique l'enregistrement à modifier.

Cet identifiant est obligatoire, et chaque API de modification renverra une exception si une valeur nulle ou vide lui est fournie.

En règle générale, cet identifiant est transmis par l'intermédiaire de la propriété "Id", mais ce n'est pas obligatoirement le cas, notamment s'il faut plusieurs informations pour identifier l'enregistrement.

En règle générale, cet identifiant peut être retrouvé par une API de recherche.

Principe 3

Toutes les propriétés scalaires (chaînes, dates, valeurs numériques, booléens) d'un objet sont considérées comme devant être modifiées (y compris les valeurs null).

Cela signifie que si vous affectez la valeur null à une propriété scalaire ou si vous ne la renseignez pas, la valeur NULL sera transmise à la donnée correspondante dans la base de données.

Cela signifie également que si vous ne renseignez pas un sous-objet, les données correspondant aux propriétés scalaires de celui-ci ne seront pas modifiées.

Pour résumer, un sous-objet omis (ou à null) n'affectera pas les données mais, s'il est renseigné, les données transmises dans ses propriétés scalaires affecteront les données.

Principe 4

Les données demandées par une API de mise à jour peuvent toujours être obtenues en utilisant une API de lecture.

Il est donc conseillé d'effectuer une lecture avant une mise à jour.

Processus conseillé pour une mise à jour

En supposant que vous souhaitez modifier certaines données d'un client (par exemple : le texte personnalisable 1 et la valeur numérique personnalisable 3), voici le processus conseillé :

Effectuer une lecture pour obtenir les données actuelles.

Il existe forcément une API de lecture pour chaque API de mise à jour.
Si l'API de lecture permet la sélection de groupes de propriétés, il est conseillé de sélectionner uniquement les données que vous souhaitez modifier.

Dans notre exemple, nous allons utiliser l'API de lecture des clients et sélectionner les groupes de propriétés 5 (textes personnalisables) et 7 (valeurs numériques personnalisables).

{
 "Page": { "PageIndex": 1, "PageSize": 1 },
 "Filters": [{ "property": 1, "constantValue": "LPH001", "comparisonOperateur": 1, "inversion": false,"logicOperator": 1 }],
 "Selection" : [5,7]
}

Le retour ressemblera à ceci.

{
  "page": { "previousPage": null, "nextPage": null, "pageCount": 1 },
  "customers": [
    {
      "id": "LPH001",
      "shortName": "LPH TESTS",
      "closed": false,
      "customText": {
        "customText01": "Texte libre 1",
        "customText02": "Texte libre 2",
        "customText03": "Texte libre 3"
      },
      "customNumeric": {
         "customNumeric01": 1.0000,
         "customNumeric02": 2.0000,
         "customNumeric03": 3.0000
       }
    }
  ]
}

Conserver les valeurs des groupes de propriétés que vous souhaitez modifier.

Dans notre exemple, il faut conserver les valeurs des groupes de propriétés 5 (textes personnalisables) et 7 (valeurs numériques personnalisables).

Donc on conserve :

customer.customText.customText01 ("Texte libre 1")
customer.customText.customText02 ("Texte libre 2")
customer.customText.customText03 ("Texte libre 3")
customer.customNumeric.customNumeric01 (1)
customer.customNumeric.customNumeric02 (2)
customer.customNumeric.customNumeric03 (3)

Effectuer les modifications souhaitées.

Utiliser l'API de mise à jour en transmettant les données conservées et les modifications souhaitées.

{
  "id": "LPH001",
  "customText": {
    "customText01": "Nouveau texte libre 1",  // Valeur modifiée
    "customText02": "Texte libre 2",  // Valeur conservée
    "customText03": "Texte libre 3"  // Valeur conservée
  },
  "customNumeric": {
    "customNumeric01": 1.0000,  // Valeur conservée
    "customNumeric02": 2.0000,  // Valeur conservée
    "customNumeric03": 30.0000   // Valeur modifiée
  }
}

Cet appel aura le même effet car l'objet des dates personnalisables est à null.

{
  "id": "LPH001",
  "customText": {
    "customText01": "Nouveau texte libre 1",  // Valeur modifiée
    "customText02": "Texte libre 2",  // Valeur conservée
    "customText03": "Texte libre 3"  // Valeur conservée
  },
  "customNumeric": {
    "customNumeric01": 1.0000,  // Valeur conservée
    "customNumeric02": 2.0000,  // Valeur conservée
    "customNumeric03": 30.0000   // Valeur modifiée
  },
  "customDate": null
}

Attention
Cet appel aura pour effet de mettre à null les textes personnalisables 2 et 3, ainsi que les valeurs numériques personnalisables 1 et 2, car ces propriétés scalaires sont manquantes.

{
  "id": "LPH001",
  "customText": {
    "customText01": "Nouveau texte libre 1",  // Valeur modifiée
  },
  "customNumeric": {
    "customNumeric03": 30.0000   // Valeur modifiée
  }
}

Attention
Cet appel aura pour effet de mettre à null toutes les dates personnalisables car l'objet des dates personnalisables est renseigné mais ses propriétés ne le sont pas.

{
  "id": "LPH001",
  "customText": {
    "customText01": "Nouveau texte libre 1",  // Valeur modifiée
    "customText02": "Texte libre 2",  // Valeur conservée
    "customText03": "Texte libre 3"  // Valeur conservée
  },
  "customNumeric": {
    "customNumeric01": 1.0000,  // Valeur conservée
    "customNumeric02": 2.0000,  // Valeur conservée
    "customNumeric03": 30.0000   // Valeur modifiée
  },
  "customDate": { }
}

Table of Contents