Projet export

Retrouvez tous les éléments concernant la configuration d’un projet exploitant un export.

Un export correspond à la création d’une archive ZIP contenant les objets touristiques et les sélections d’un projet mise à disposition à intervalle régulier.

Il est important de bien distinguer les exports périodiques, réalisés selon la fréquence d’export du projet, et les exports ponctuels, qui sont fait exceptionnellement sur demande d’un utilisateur Apidae, le plus souvent le développeur ou le responsable technique du projet.

La configuration du contenu des exports est réalisée via l’interface Diffuser / Projets / Mes Projets / . En tant que développeur, vous avez accès à cette interface si votre client vous a déclaré comme prestataire sur le projet et s’il vous a affecté les droits de configuration technique du projet.

Configuration de l’export

La configuration du format de l’export et des éléments techniques se fait via les outils pour les développeurs depuis la page du projet. Cette configuration permet :

  • d’activer / désactiver la génération du fichier d’export : en cochant / décochant la technologie Exports
  • d’activer / de désactiver les exports périodiques pour ce projet en choisissant la fréquence de génération
  • d’inclure ou non les objets masqués dans les objets mis à disposition (recommandé : décoché)
  • de choisir le format d’export : JSON ou XML.
  • de définir la version du format de sortie : V1 ou V2 (tout nouveau développement doit utiliser la version la plus récente des formats)
  • de grouper les objets touristiques exportés par paquets de 50. Si décoché chaque objet exporté est placé dans un fichier individuel.
  • d’activer l’export des dates d’ouvertures. Si vous activez l’export des dates d’ouverture, les objets sont exportés avec la liste des jours d’ouverture dans le champs datesOuverture (ces informations étant calculées à partir des périodes de l’objet). Une visibilité de 1 an minimum est fournie sur les ouvertures ; le processus d’export ré-exporte les objets régulièrement pour garantir cette visibilité (exemple : l’objet est fourni avec une liste des ouvertures sur 1 an et 3 mois. Si l’objet n’est pas modifié, il sera tout de même re-exporté au bout de 3 mois de manière à fournir à nouveau la visibilité à 1 an).
  • de définir une URL vers un web service de notification. A la fin de l’export, l’application envoie des informations concernant l’issue de l’export au web service ainsi désigné.
    > Description de la notification
  • de définir une liste d’adresses e-mail à contacter en cas d’erreur d’export ou de fin d’export ponctuel. Ces adresses e-mail doivent être séparées par des espaces, des virgules ou des points-virgules.
  • d’inclure ou non les informations sur le projet et le membre sources du flux.
  • de définir la liste des adresses IP depuis lesquelles vous sollicitez des ressources APIDAE.

Si vous choisissez d’inclure les objets masqués, il vous est nécessaire de prendre en compte le champ state des objets de manière à limiter les affichages publics aux seuls objets ‘PUBLISHED’. Il est recommandé de laisser cette case décochée.

Format JSON / XML

Un des choix de configuration principal de l’export est le choix du format. Les exports sont disponibles au format JSON et au format XML.

Pour choisir entre le format JSON et le format XML, vous devez prendre en compte les points suivants :

  • le format natif de la plate-forme et le format JSON, et le format XML est obtenu par transformation. Le format XML est donc un format secondaire, mais dont l’entretien et l’évolution à la même vitesse que le format JSON est prévu (puisque de manière automatique)
  • Les APIs ne sont disponibles qu’au format JSON ; si vous désirez exploiter conjointement exports et API, il peut être plus judicieux d’opter pour le JSON
  • Le format XML peut vous permettre d’exploiter des outils spécifiques et que vous contrôlez bien et qui ne possèdent pas d’équivalent pour JSON (exemple : xpath)

Le format XML a été mis en place de manière à permettre l’utilisation d’un socle technologie XML pour le parsing et la récupération des informations sur les objets touristiques. Il ne s’agit pas d’un export au format TIF.

Spécificités du format XML

La documentation se focalise sur les flux JSON, mais il est aisé de déterminer le format XML à partir du format JSON une fois les spécificités suivantes comprises :

Les identifiants et les types sont spécifiés en attributs :

JSON

{"id" : 12347, "type" : "ACTIVITE"}

XML 

<!-- déclaration id et type -->

Les liens mono-valué et multi-valués entre entités sont encapsulés. Par exemple, pour les champs commune (sur localisation) et perimetreGeographique :

JSON

commune : { id : 1 }

XML

<!-- nom du champ -->
    <!-- type de l'objet -->

JSON

perimetreGeographique : [ { id : 1 }, { id : 3 } ]

XML

<!-- nom du champ -->
    <!-- type de l'objet -->

La geolocalisation n’exploite pas le format geojson:

JSON

"geoJson" : {
        "type" : "Point",
        "coordinates" : [ 6.477635, 46.373565 ]
      }

XML



    46.373565
    6.477635

Si vous voulez apprécier sur des objets réels le format, vous pouvez utiliser les dev-tools pour obtenir rapidement des représentations des objets désirés :
JSON : http://base.apidae-tourisme.com/diffuser/dev-tools/serialisation/json-export/
XML : http://base.apidae-tourisme.com/diffuser/dev-tools/serialisation/xml-export/

Il n’existe actuellement pas de fichier XSD descriptif du format XML pour les raisons suivantes :

  • Le coeur du moteur de génération cible le JSON, et il ne supporte que la génération des schémas JSON.
  • Le développement et l’évolution de Apidae impliquera de faire évoluer le modèle ; nous ne mettrons pas en oeuvre d’évolutions qui cassent le modèle et les développements existants, par contre la mise en place de nouvelles données ajoutera potentiellement de nouveaux champs dans le futur. De ce fait, nous ne désirons pas que des procédures de validation trop rigides bloquent les interfaces alors que les formats resteront compatibles.
  • Les fichiers de schéma JSON fournis servent avant tout de liste exhaustive des champs disponibles dans les exports, donc de documentation, et pas de document de validation.

De ce fait, nous encourageons les utilisateurs du format XML à se baser sur la documentation, les schémas JSON et des exemples de sérialisation d’objet pour l’analyse du format.