Documentation technique

v002/donnees-privees/

Modes d’utilisation

La même API sert simultanément à l’ajout ou à la suppression de descriptifs privés. La distinction est faite au travers des méthodes HTTP utilisées pour émettre la request vers l’API.

• L’ajout de descriptifs se fait par un appel utilisant la méthode PUT
• La suppression de descriptifs se fait par un appel utilisant la méthode DELETE

Exemples

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer". $token));
curl_setopt($ch, CURLOPT_URL, "http://lesiteapidae/api/v002/donnees-privees/");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT" );
curl_setopt($ch, CURLOPT_ENCODING, 'UTF-8');
curl_setopt($ch, CURLOPT_POSTFIELDS, $formParameters);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

Exemple 2 : Méthode de suppression de critères :
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer". $token));
curl_setopt($ch, CURLOPT_URL, "http://lesiteapidae/api/v002/donnees-privees/");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE" );
curl_setopt($ch, CURLOPT_ENCODING, 'UTF-8');
curl_setopt($ch, CURLOPT_POSTFIELDS, $formParameters);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

Formulaire d’envoi des données

A l’image de l’api en écriture, un appel au web-service de gestion des descriptifs privés s’articule autour d’un formulaire au format multipart/form-data.

Ce formulaire comporte un unique champ donneesPrivees dont le contenu est encodé au format JSON, permettant de transmettre les identifiants des objets touristiques et les descriptifs privés à manipuler.

Description du JSON

{
        "objetsTouristiques" : [
                {
                        "id" : xxx,
                        "donneesPrivees" : [
                                {
                                        "nomTechnique" : "a",
                                        "descriptif" : {
                                                "libelleFr" : "fr",
                                                "libelleEn" : "en"
                                         }
                                }
                        ]
                }
        ]
}

1. objetsTouristiques[] :[Obligatoire] Liste des objets touristiques à mettre jour avec leurs descriptifs privés.
2. objetsTouristiques[i].id :[Obligatoire] Identifiant de l’objet touristique à mettre à jour.
3. objetsTouristiques[i].donneesPrivees[] : [Obligatoire] : Liste des descriptifs privés à ajouter/modifier/supprimer
4. objetsTouristiques[i].donneesPrivees[j].nomTechnique : [Obligatoire] Identifiant du descriptif à ajouter/modifier/supprimer. Cet identifiant est défini par l’administrateur ayant créé le champ et à obtenir auprès de celui-ci.
5. objetsTouristiques[i].donneesPrivees[j].descriptif : [Facultatif] Contenu multilingue du descriptif. Comme les autres textes multilingues de l’application, il est constitué d’un attribut par langue (libelleFr pour le Français, libelleEn pour l’anglais, etc …). Le champ descriptif est obligatoire en ajout/modification (PUT). Il est facultatif en suppression (DELETE)
   

Règles d’utilisation

1. La liste des identifiants d’objets touristiques à mettre à jour est limitée à 50 valeurs. Au delà, la méthode renvoie une erreur et aucun objet n’est mis à jour.
2. Aucune erreur n’est remontée si un/des identifiant(s) d’objets touristiques passés en paramètre n’existent pas
3. Pour qu’un descriptif puisse être altéré (création/mise à jour/suppression), le membre propriétaire du projet doit être le membre propriétaire de ce descriptif. Une erreur est générée si cette condition n’est pas respectée.
4. Ce même membre doit avoir le droit « Gestionnaire de descriptifs privés ». Une erreur est générée si cette condition n’est pas respectée.
5. A l’identique de la manipulation des critères internes, les modifications sont appliquées sans créer de brouillon de l’objet

Exemples

{
         "objetsTouristiques" : [
                 {
                         "id" : 111111,
                         "donneesPrivees" : [
                                 {
                                         "nomTechnique" : "1_ChampPrive",
                                         "descriptif" : {
                                                 "libelleFr" : "Descriptif_1",
                                                 "libelleEn" : "Content_1"
                                          }
                                 },
                                 {
                                         "nomTechnique" : "2_ChampPrive",
                                         "descriptif" : {
                                                 "libelleFr" : "Descriptif_2",
                                                 "libelleEn" : "Content_2"
                                          }
                                 }
                         ]
                 },
                 {
                         "id" : 222222,
                         "donneesPrivees" : [
                                 "nomTechnique" : "1_ChampPrive",
                                 "descriptif" : {
                                         "libelleFr" : "Descriptif_3",
                                         "libelleEn" : "Content_3"
                                  }
                         }]
                 }
         ]
 }

{
        "objetsTouristiques" : [
                {
                        "id" : 111111,
                        "donneesPriveesASupprimer" : [
                               "1_ChampPrive", "2_ChampPrive"
                        ]
                }
        ]
}

Retours de la méthode

La méthode renvoie un objet JSON comportant les champs suivants :

errorType

type : chaîne de caractères
description : Type d’erreur technique rencontrée lors du traitement.
valeurs possibles :

• ECRITURE_FORBIDDEN : vous ne disposez pas de droits suffisants sur le projet.
• ECRITURE_BAD_REQUEST : Le formulaire avec les données JSON n’a pas été fourni.
• ECRITURE_INVALID_JSON_DATA : les données JSON à injecter n’ont pas le format attendu.

id

type : tableau d’entiers
description : Liste des identifiants des objets touristiques mis à jour. Cet attribut est présent uniquement si le traitement s’est déroulé correctement.

status

type : chaîne de caractères
description : indique le résultat de l’appel.
valeurs possibles :

• MODIFICATION_DONNEES_PRIVEES : Les descriptifs ont été mis à jour ou créés sur les objets touristiques Si le champ status renvoie cette valeur, le traitement s’est déroulé correctement.
• SUPPRESSION_DONNEES_PRIVEES : Les descriptifs ont été supprimés des objets touristiques. Si le champ status renvoie cette valeur, le traitement s’est déroulé correctement.
• NO_ACTION : Aucune action n’a été réalisée, suite à la présence de contrôles ayant échoué.

message

type : chaîne de caractères
description : Message présent uniquement dans le cas d’un traitement en anomalie et explicitant cette anomalie.

Exemples de retour

{
    id = [111111, 222222],
    status = "MODIFICATION_DONNEES_PRIVEES"
}

{
    id = [111111],
    status = "SUPPRESSION_DONNEES_PRIVEES"
}

{
    errorType = "ECRITURE_BAD_REQUEST",
    message = "Paramètre 'donneesPrivees' manquant dans la requête"
}

{
    status = "NO_ACTION",
    message = "La liste des objets à modifier est trop importante. Max attendus : 50 - Reçus : 52"

}