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] }
- id :[Obligatoire] Tableau d’identifiants des objets touristiques à mettre à jour.
- 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)
- 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
- 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.
- 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
- La liste de critères internes doit toujours comporter au moins 1 élément. La méthode renvoie une erreur dans le cas contraire.
- 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.
- 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" }