Prérequis
Pour pouvoir consulter les API Apidae, il vous faut un compte développeur ainsi qu’un projet (un projet mis à disposition par votre client, ou un projet de test).
Votre première consultation des APIs
Munissez-vous d’un identifiant d’objet, d’un identifiant de projet et de votre clé d’API.
Ouvrez votre navigateur et saisissez dans la barre d’adresse (pour l’identifiant 123457, l’identifiant de projet 1 et la clé xxxxx, à remplacer par vos valeurs) :
https://api.apidae-tourisme.com/api/v002/objet-touristique/get-by-id/123457?apiKey=xxxxx&projetId=1
Voilà, vous venez d’obtenir un objet au format JSON. Des informations nécessaires ne sont pas présentes ? La sortie par défaut d’une consultation des APIs est effectivement un format condensé. Vous pouvez enrichir votre requête de manière à détailler le résultat obtenu :
> Filtrage des données
> Filtrage des langues
N’oubliez pas, choisir de manière judicieuse vos champs vous permettra d’obtenir une réponse plus compacte, plus rapide et plus lisible. Voici un exemple de recherche qui retourne les objets de type RESTAURATION dans la sélection 12347 (les sélections sont configurables dans les interfaces de gestion du projet Apidae) (n’oubliez pas de consulter l’ensemble des critères disponibles) :
https://api.apidae-tourisme.com/api/v002/recherche/list-objets-touristiques?query={"projetId":1,"apiKey":"xxxxx","criteresQuery":"type:RESTAURATION","selectionIds":[12347]}
N’oubliez pas non plus que des outils développeurs sont disponibles.
> Outils pour les développeurs
Les exemples ci-dessus permettent de tester rapidement les services. Cependant, lors de l’exploitation des API il est primordial de veiller à bien échapper les paramètres de votre requête (voir paragraphe suivant sur les usages sur la construction de requête).
Bibliothèques Apidae
Les exemples et conseils suivants sont destinés à décrire les mécanismes de base pour accéder aux données Apidae via les API. Toutefois, il existe des outils ou des exemples d’exploitation Apidae à votre disposition pour vous faciliter la tâche et qui réalisent pour vous une partie des opérations décrites dans la suite de cette page.
Les bons usages pour la construction d’une requête
Pour éviter les dysfonctionnements lors de la consultation en recherche des API, il est important d’appliquer les règles suivantes :
Les paramètres GET ou POST doivent être échappés
Les paramètres passés dans l’url doivent être échappés pour être traités correctement. Par exemple, les clés d’API comportent souvent des caractères spéciaux comme # ou ?. Il est important de bien veiller à échapper ces caractères, respectivement %23 et %3F (cette liste de caractères spéciaux n’est pas exhaustive). En PHP, cette phase peut être réalisée de la manière suivante :
$apiKey = 'fausseCleAvec?#EtAutresChar!Speciaux';
$projetId = 100000000;
$url = 'https://api.apidae-tourisme.com/api/v002/objet-touristique/get-by-id/123456';
$url .= '?';
$url .= 'projetId='.urlencode($projetId);
$url .= '&apiKey='.urlencode($apiKey);
print $url;
# https://api.apidae-tourisme.com/api/v002/objet-touristique/get-by-id/123456?projetId=10000000&apiKey=fausseCleAvec%3F%23EtAutresChar%21SpeciauxLa requête doit être dans un format JSON valide
La requête, stockée dans le champ GET ou POST query, doit être dans tous les cas un objet JSON valide. Pour construire la requête, il est donc conseillé :
- d’utiliser en fonction du langage utilisé, soit des objets, soit des hashmaps pour construire les différents champs de votre requête. Pendant cette construction, vous n’avez normalement pas besoin d’échapper de caractères
- puis d’utiliser les outils disponibles avec votre langage pour procéder à la sérialisation JSON
- Enfin, une fois la chaîne JSON obtenue, de l’injecter dans la requête en utilisant un échappement / encodage d’URL
En PHP, cette construction peut être réalisée comme suit :
$apiKey = 'cleApiAvecUn#';
$projetId = '150432';
$searchQuery = 'Cheval';
$requete = array();
$requete['apiKey'] = $apiKey;
$requete['projetId'] = $projetId;
$requete['searchQuery'] = 'Cheval';
$url = 'https://api.apidae-tourisme.com/api/v002/recherche/list-objets-touristiques';
$url .= '?';
$url .= 'query='.urlencode(json_encode($requete));
print $url;
# https://api.apidae-tourisme.com/api/v002/recherche/list-objets-touristiques?query=%7B%22apiKey%22%3A%22cleApiAvecUn%23%22%2C%22projetId%22%3A%22150432%22%2C%22searchQuery%22%3A%22Cheval%22%7DLa liste des services
Vous pouvez consulter la liste des services dans la documentation.
Optimiser mon utilisation des services
De manière à assurer le meilleur fonctionnement pour tous, ainsi que pour vos visiteurs, bien choisir votre méthode d’intégration de Apidae ainsi qu’optimiser vos développements est fondamental.
Après avoir découvert Apidae et avant de vous lancer dans la réalisation finale, il vous faudra bien vérifier que les APIs conviennent à votre usage.
Les mécanismes d’optimisation à implémenter sont les suivants. Ils sont à moduler en fonction de la fréquentation attendue de votre site. Leur mise en oeuvre vous permettra d’assurer une bonne performance pour votre projet ainsi que de vous affranchir en totalité ou en partie d’Apidae en cas d’indisponibilité.
- Cache sur les pages accédées massivement (accueil, page maître de rubrique…)
- Mise en cache des données des objets touristiques ;
- Utilisation préférentielle des services retournant des listes d’identifiant avec utilisation du cache d’objets touristiques pour la récupération des données ;
- Cache (sur votre serveur) des multimédias (images, fichiers) utilisés couramment (un cache des seules images peut suffire si les autres fichiers sont simplement mis à disposition pour téléchargement) ;
- Cache sur les recherches fréquentes.
Exploiter les sélections
Même si les API vous proposent des fonctionnalités de recherche, favorisez les sélections individuelles d’Apidae pour vos recherches :
- les sélections permettent de répartir la responsabilité entre les contenus (déterminés par votre client via les sélections) et les développements
- les sélections permettent à votre client d’intervenir de manière autonome sur les contenus
- s’il ne désire pas les gérer lui-même, votre client peut vous confier la réalisation de sélections
- les possibilités de requêtage des sélections sont plus avancées que celles de l’API
- les sélections sont pré-calculées pour optimiser les temps de réponse
- il est possible de combiner une sélection avec des critères de recherche API si nécessaire
Timeout sur les requêtes
Utiliser systématiquement un timeout sur vos requêtes. Déterminer et ajuster ce timeout en fonction de votre utilisation des API (il va dépendre de vos paramètres de pagination, des champs consultés…). Une durée maximum de 2 à 3 secondes peut paraitre un bon choix en fonction de vos observations.
Utiliser un timeout trop long handicapera à la fois la plateforme Apidae et votre site web :
- vos requêtes seront plus lentes,
- attendre plus longtemps n’est pas une garantie d’obtenir un résultat,
- des timeout courts faciliteront le retour à la normale de la plate-forme en cas de saturation
Ressources :
- PHP / fget : http://www.php.net/manual/fr/context.http.php
- PHP / cUrl : http://www.php.net/manual/fr/curl.constants.php
Gérer correctement les cas d’erreur
En cas d’erreur :
- Évitez de faire tourner la requête en erreur en boucle,
- Prenez en compte les cas d’erreur sur votre application de manière à résister aux potentielles coupures de service
Échapper correctement vos requêtes
Si vos requêtes ne sont pas échappées correctement, vous rencontrerez des problèmes dès que des caractères spéciaux seront utilisés dans vos requêtes (cf paragraphe plus haut sur l’échappement)
Exploiter tous les services mis à votre disposition
En particulier, pensez à utiliser les services orientés identifiants ; ils sont plus rapides que les services renvoyant les informations des objets touristiques. Une utilisation combinée d’un cache (pour les informations des objets touristiques) et des services de recherche orientés identifiants améliorera vos temps de consultation.
Exploitez aussi les possibilités de filtrage des champs en ciblant les champs que vous voulez utilisez ; les réponses seront allégées et plus rapides. N’utilisez l’alias @all que pour vos tests.
Minimiser vos appels
Certains besoins nécessitent de combiner plusieurs appels sur les API pour être réalisés.
Dans ces cas, privilégiez la mise en place de caches ainsi qu’un choix judicieux des services utilisés pour minimiser vos appels ; vos temps de traitement seront optimisés.
Exemple d’optimisation : récupérer la première date pour laquelle il existe une FETE_ET_MANIFESTATION dans une sélection donnée
- Solution 1 (inefficace) : faire une requête par jour sur l’agenda sur la sélection et s’arrêter quand il existe un résultat
- Solution 2 (plus efficace) : faire une recherche agenda sur la sélection en limitant à 1 le nombre de résultats. Dans la réponse, le premier jour avec un résultat correspond au jour qu’on recherche
Un besoin particulier, un doute sur la solution la plus simple à mettre en place pour un besoin spécifique. Contactez-nous, nous pourrons sûrement vous aider à valider vos choix techniques.