Documentation technique

v002/criteres-internes/

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

$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

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

{
    "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

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

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

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

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

}

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

}

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