Les API sont le moyen le plus simple d’accéder à la donnée Apidae. Le contenu peut être préparé par votre client à l’aide des sélections, et les services exposés vous permettent de récupérer facilement les éléments à afficher.
Introduction
L’objectif des API est de permettre d’accéder en direct aux contenus de Apidae.
Elles peuvent être utilisées seules ou en complément des exports.
Dans le cas de projets à fort trafic, à forte volumétrie d’objets touristiques (> 5.000 objets) ou qui nécessitent de retravailler fortement la donnée Apidae, il est conseillé de recourir aux exports.
> Choisir entre API et exports
Principes généraux
Les API Apidae sont des API Rest/JSON.
Elles ont pour objectif de permettre une manipulation facile de l’information et proposent une vue très orientée métier de la donnée Apidae.
> Documentation sur le format des objets touristiques
Utilisation des sélections
Dans les interfaces de configuration du projet, il est possible d’accéder à la configuration des sélections du projet. Les sélections, généralement configurées par votre client, constituent le contenu de votre projet : ce sont des listes d’objets touristiques, mises à jour périodiquement (chaque nuit généralement), construites à partir de filtres ou de sélection individuelles d’objets touristiques.
Les API étant pourvues de fonctionnalités de recherche, il est possible de cumuler utilisation des sélections et filtrage au moment de la requête web-servicec de manière à obtenir des résultats dynamiques (exemple : filtrage d’une sélection via une recherche plein texte).
Il est important de déterminer avant toute réalisation de projet qui est responsable de la constitution des sélections.
Passage des arguments
Pour le passage des arguments, il faut veiller à échapper correctement tous les éléments qui se trouvent dans les champs passés en GET ou en POST.
Dans le cas du GET, il est notamment impératif d’échapper chacun des paramètres (typiquement en PHP, en utilisant url_encode()).
Les navigateurs échappent automatiquement les paramètres même non échappés dans l’URL avant envoi au serveur. Il est donc possible qu’une requête fonctionne dans votre navigateur et pas lorsque vous faites des appels programmatiques. Si vous êtes confronté à cette situation, vérifier l’échappement de votre requête.
Pour la requête de recherche, au format JSON, il est conseillé d’utiliser des outils de conversion automatique (json_encode en php).
Pour les développeurs utilisant PHP, Apidae fournit une bibliothèque permettant d’exploiter les API : sitra-api-php.
> Exemples et conseils pour la consultation en PHP
> Présentation du projet sitra-api-php
> Exemple de projets exploitant Apidae
Authentification des appels
Les appels aux web-services sont soumis à l’utilisation d’un couple identifiant de projet / clé d’API.
Pour connaître la clé d’API associée à un projet, vous devez vous rendre sur la fiche du projet dans le menu Diffuser > Projets > Mes projets, puis en sélectionnant le projet dont vous souhaitez récupérer la clé.
Si vous souhaitez réaliser des tests sur les API, il est possible de créer un projet de test. Ce type de projet vous permet de commencer à tester l’utilisation des API sur une partie restreinte des données Apidae.
Pour créer un projet de test, rendez-vous sur la page de projet dans Diffuser > Projets > Mes projets, puis cliquez sur le bouton Créer un projet de test, en haut à droite. Une fois votre projet créé, vous trouverez la clé d’API au même endroit que pour un projet classique.
Pour les services get-by-*, les informations d’authentification sont à fournir en paramètre (dans l’url pour le GET, sous forme d’un champ pour le POST) :
...?apiKey=<clé>&projetId=Pour les recherches, ces informations sont à fournir dans l’objet de requête :
{
...
"apiKey" : "<clé>",
"projetId" : ,
...
}Pagination des résultats
Tous les résultats listant des objets touristiques sont paginés. Il est nécessaire de préciser les paramètres count et first pour contrôler le fonctionnement de la pagination.
> Documentation sur le format de la requête
Configuration d’un projet Apidae pour utiliser les API
Tout projet de diffusion Apidae permet de faire des appels via API à partir du moment où la technologie API est sélectionnée.
Si vous utilisez des sélections (conseillé), il est possible de configurer la fréquence de mise à jour des sélections également dans la partie Configuration technique.
Filtrage des résultats
Toutes les réponses API concernant les objets touristiques sont filtrées. Il est impératif de paramétrer (au niveau de la requête) le filtrage des champs et des langues si vous désirez obtenir plus que les champs exposés par défaut.
> Filtrage des champs
> Filtrage des langues
Présentation des web-services Apidae
Les services Apidae appartiennent à 3 catégories générales.
- La récupération unitaire d’objet touristique : services simples qui permettent de récupérer un objet par son identifiant ou son identifier. Les seuls paramètres nécessaires sont les informations de connexion, l’identifiant / identifier et les paramètres de filtrage ;
- La recherche d’objets touristiques : services qui permettent de consulter les sélections d’un projet. Des outils de filtrage basiques permettent d’affiner le résultat obtenu en ajoutant des contraintes sur la recherche.
- Ces services sont déclinés en 2 versions : une qui renvoit uniquement les identifiants des objets, une autre qui renvoit les objets (dans la limite du paramétrage du filtrage)
- Les résultats peuvent être formatés en liste simple (API recherche) ou avec une répartition par date (API agenda, concerne uniquement une partie des objets touristiques)
- La consultation du référentiel