Vous commencez à travailler avec Apidae, vous travaillez déjà avec Apidae et vous désirez vérifier si les technologies utilisées sont toujours adéquates. Vous trouverez ici comment réaliser vos choix techniques parmi les outils Apidae pour vos développements.
Bien choisir comment s’interfacer avec Apidae est fondamental pour vos futurs développements. Choisir entre un mode de fonctionnement export et un mode de fonctionnement API est fondamental.
Ce document vous rappelle les possibilités offertes par les APIs et les exports ainsi que les différentes questions à vous poser qui feront pencher la balance d’un côté ou de l’autre.
Fonctionnalités proposées
| API | Exports | |
|---|---|---|
| Rapidité de prise en main | Prototypage rapide Permet d’évaluer rapidement la richesse des informations Apidae. | Investissement plus important, mais qui permet d’implémenter de manière plus aisée un retraitement des données spécifiques lors du mécanisme d’import. |
| Format | Format JSON unifié | Format JSON unifié et format XML (le format des exports est légèrement adapté des API de manière à séparer le référentiel) |
| Requêtage | Possibilité d’utiliser les sélections API de requêtage disponible API de requêtage agenda disponible (résultats par jour d’ouverture) | Possibilité d’utiliser les sélections Possibilité d’importer et de retraiter les informations de manière à implémenter chez vous le requêtage de votre choix |
| Fourniture du thésaurus, des sélections, … | API de référentiel disponibles | Les listes des éléments du thésaurus, des communes, des sélections, des critères internes sont exportables |
| Différentiel | Non | Oui |
| Volumétrie / nombre d’objets exploitables | Limité, paginé à 200 objets maximum par page | Non limité |
| Mode déconnecté (fonctionnement en cas de coupure de service Apidae) | Non | Oui |
La question à poser
Quel est le nombre d’objets touristiques exploités par mon site ?
Si vous exploitez plusieurs milliers (> 5000) d’objets touristiques, utilisez les exports.
En-dessous, cela dépend des technologies employées :
- javascript sur client web sans cache chez vous sur un site à forte affluence : export
- javascript sur client web sur un site à faible affluence : API ou export
- récupération côté serveur avec mécanismes de cache : API ou export
Mon utilisation impose-t-elle de retraiter des données ?
Si vous êtes obligés de retraiter des données de votre côté (de manière à agréger d’autres sources d’informations par exemple), l’export est le bon choix.
Vos développements nécessiteront un investissement minimum, qui doit vous permettre de vous intégrer dans le mécanisme d’export, et c’est la façon d’obtenir le maximum de souplesse.
Est-ce que les possibilités de requêtage des API me suffisent ?
Les API proposent des fonctionnalités de requêtage conçues pour couvrir les besoins les plus courants ; elles vous permettront de filtrer les sélections mise en place dans la configuration du projet. Cependant, elles ne répondront pas forcément aux besoins spécifiques ou pointus requis par certains clients.
Dans ce cas, il faut privilégier les exports qui vous permettront d’intégrer les données chez vous et de bâtir votre propre moteur de recherche.
Quel est mon objectif à court terme, à long terme ?
Vous vous lancez dans un nouveau concept ? Vous cherchez de nouveaux usages ? Vos besoins sont à court terme mesurés, mais vous comptez bien sur le long terme aboutir à une application de taille conséquente ?
Optez pour les APIs, mais soyez prêt à faire le saut vers les exports le jour où vous rencontrez le succès.
Peut-on utiliser à la fois les API et les exports
Vous pouvez utiliser si vous le souhaiter à la fois les API et les exports :
- Utilisation des APIs pour forcer le rafraichissement d’un objet au cours de la journée (attention, ce mode de fonctionnement est indiqué seulement pour des rafraichissements ponctuels)
- Utilisation des APIs pour des fonctions annexes (recherche d’objets touristiques à proximité d’un objet de ma sélection)
Il vous appartient de choisir sur la base des besoins exprimés la solution la plus judicieuse. Attention toutefois à bien traiter les différences minimes de format qui existent entre exports et API.
Format des API et des exports
Quelle sont les différences entre le format des APIs et le format des exports ?
Le but de nos développements a été d’aboutir à un format de sortie des APIs et des exports les plus proches possibles. Cet objectif nous semble important pour les raisons suivantes :
- permettre aux développeurs d’intégrer l’écosystème Apidae de manière plus simple : il est plus facile de faire ses premières armes et découvrir les données via les APIs que de commencer avec l’export
- simplifier et unifier l’écosystème
Toutefois, des différences existent de manière à séparer la définition des objets touristiques et des éléments du référentiel (communes, éléments de référence, critères internes, …).
L’ensemble des spécificités de format est disponible ici.
Un exemple d’élément modifié est la présentation d’un élément de référence.
Le format de sortie d’un élément de référence est le suivant :
"structureType" : {
"elementReferenceType" : "StructureType",
"id" : 3168,
"libelleFr" : "Prestataire",
"ordre" : 21,
"description" : "Utiliser ce critère pour qualifier toutes les structures pour lesquelles il n'existe pas le critère précis dans la liste actuelle."
}Pour les exports, le fonctionnement vis-à-vis des éléments de référence est différent. Un fichier spécifique contient l’ensemble des éléments de référence au format JSON.
De ce fait, dans l’export de l’objet touristique, on limite la sortie au seul identifiant :
"structureType" : { "elementReferenceType": "StructureType", "id": 3168 }