Documentation technique

v002/donnees-privees/

L’API de gestion des descriptifs privés permet d’ajouter ou supprimer une liste de descriptifs à une liste d’objets touristiques. Ces descriptifs sont des libellés multilingues rattachés à des champs privés. La liste des champs disponibles pour un membre est gérée par les administrateurs de ce membre.
Cette page décrit la structure générale d’une requête (hors structure des données touristiques).

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
Exemple 1 : Méthode d’ajouts de descriptifs privés :
$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

Exemple 1 : Modification de 2 objets touristiques  (mise à jour de 1_ChampPrive et 2_ChampPrive sur le premier. Seul 2_ChampPrive est mis à jour sur le 2e) :
{
        "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″
                                 }
                        }]
                }
        ]
}
Exemple 2 : Suppression d’un descriptif privé sur un objet touristique :
{
        "objetsTouristiques" : [
                {
                        "id" : 111111,
                        "donneesPrivees" : [
                                {
                                        "nomTechnique" : "1_Champ1"
                                }
                        ]
                }
        ]
}

 

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

Exemple 1 : Retour valide suite à l’ajout de descriptifs
{
    id = [111111, 222222],
    status = "MODIFICATION_DONNEES_PRIVEES"
}
Exemple 2 : Retour valide suite à la suppression de descriptifs
{
    id = [222222],
    status = "SUPPRESSION_DONNEES_PRIVEES"
}
Exemple 3 : Retour en erreur suite à une request émise sans le paramètre donneesPrivees (données au format JSON)
{
    errorType = "ECRITURE_BAD_REQUEST",
    message = "Paramètre 'donneesPrivees' manquant dans la requête"
}
Exemple 5 : Retour en erreur suite à la présence d’un trop grand nombre d’objets touristiques à mettre à jour
{
    status = "NO_ACTION",
    message = "La liste des objets à modifier est trop importante. Max attendus : 50 - Reçus : 52"

}