v002/criteres-internes/

L’API de gestion des critères internes permet d’ajouter ou supprimer une liste de critères internes à une liste d’objets touristiques. Cette page décrit la structure générale d’une requête (hors structure des données touristiques). Des pages annexes décrivent en détail le format des données touristiques.

Modes d’utilisation

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

  • L’ajout de critères internes se fait par un appel utilisant la méthode PUT
  • La suppression de critères internes se fait par un appel utilisant la méthode DELETE

Exemples

PHP

Exemple 1 : Méthode d’ajouts de critères :

$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer". $token));
curl_setopt($ch, CURLOPT_URL, "http://lesiteapidae/api/v002/criteres-internes/");
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/criteres-internes/");
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 critères internes s’articule autour d’un formulaire au format multipart/form-data.

Ce formulaire comporte un unique champ criteres dont le contenu est encodé au format JSON, permettant de transmettre les identifiants des objets touristiques et des critères internes à manipuler.

Description du JSON

{
    "id" : [X1, ..., Xn],
    "criteresInternesAAjouter" : [Y1, ..., Yn]
    "criteresInternesASupprimer" : [Z1, ..., Zn]
}
  1. id :[Obligatoire] Tableau d’identifiants des objets touristiques à mettre à jour.
  2. criteresInternesAAjouter : [Facultatif] Tableau d’identifiants des critères internes à ajouter. Ce paramètre est obligatoire dans le cadre d’un appel à la méthode d’ajout de critères (méthode PUT). Il est interdit dans le cadre d’un appel à la méthode de suppression de critères (méthode DELETE)
  3. criteresInternesASupprimer : [Facultatif] Tableau d’identifiants des critères internes à supprimer. Ce paramètre est obligatoire dans le cadre d’un appel à la méthode de suppression de critères (méthode DELETE). Il est interdit dans le cadre d’un appel à la méthode d’ajout de critères (méthode PUT)

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. Si un objet touristique fait partie de la liste, il est mis à jour ( = date de dernière mise à jour réactualisée) même si les critères internes à ajouter ou supprimer sont déjà respectivement présents ou absents de l’objet
  3. La liste de critères internes doit toujours comporter au moins 1 élément. La méthode renvoie une erreur dans le cas contraire.
  4. Seuls les critères internes utilisables par le membre du projet sont pris en compte. Les autres identifiants sont ignorés, sans message d’erreur.
  5. A l’identique de la saisie des critères internes dans l’application, les modifications sont appliquées sans créer de brouillon de l’objet

Exemples

Exemple 1 : Ajout de 3 critères internes à 2 objets touristiques  :

{
    "id" : [15732, 25784], 
    "criteresInternesAAjouter" : [204, 638, 560]
}

Exemple 2 : Suppression de 2 critères internes de 3 objets touristiques :

{
    "id" : [15732, 25784, 45678],
    "criteresInternesASupprimer" : [204, 638]
}

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 :

  • AJOUT_CRITERES : Les critères internes ont été ajoutés aux objets touristique. Si le champ status renvoie cette valeur, le traitement s’est déroulé correctement.
  • SUPPRESSION_CRITERES : Les critères internes 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 critères

{
    id = [15732, 25784],
    status = "AJOUT_CRITERES"
}

Exemple 2 : Retour valide suite à la suppression de critères

{
    id = [15732, 25784, 45678],
    status = "SUPPRESSION_CRITERES"
}

Exemple 3 : Retour en erreur suite à une request émise sans le paramètre criteres (données au format JSON)

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

Exemple 4 : Retour en erreur suite à un appel PUT dont le json contient le champ criteresInternesASupprimer au lieu de criteresInternesASupprimer

{
    errorType = "ECRITURE_INVALID_JSON_DATA",
    message = "Paramètre 'criteres' : les données n'ont pas un format JSON valide : Unrecognized field \"criteresInternesASupprimer\" [...]"

}

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"

}

Exemple 6 : Retour en erreur suite à l’absence de critères internes renseignés

{
    status = "NO_ACTION",
    message = "La liste des identifiants de critères internes à traiter n'est pas renseignée"
}