API Import

Règles de gestion relatives à l’import : 

• Pour le BO Offre Théorique :

• Les jeux de données importés seront restreints à une période calendaire maximale autorisée à compter du jour de l’import (actuellement fixée à 1 ans). Les calendriers sortants de cette période seront tronqués et s’ils se réduisent à aucun jour valide, ils ne seront pas importés, de même que les objets de l’offre qui leur sont strictement rattachées (courses, missions, itinéraires). 

• De même, un début de période inférieur à la date T du jour sera tronqué au-delà d’une limite d’un nombre de jours (ce seuil sera fixé par Ile-de-France Mobilités). Une alerte simplifiée précisera la réduction du jeu de donnée à l’import. 

• Si au final, aucune donnée n’est importée, le jeu de données sera rejeté.

• Les données importées sont regroupées dans un fichier ZIP, la taille de celui-ci ne devra pas excéder 80Mo. 

Import via l’IHM

Lors d’un import manuel par l’IHM, l’opérateur doit fournir un fichier contenant l’offre à importer sous la forme d’un fichier ZIP tel qu’il est défini dans le chapitre Organisation des imports. Dans le cas de l'import Offre Théorique, le ZIP ne pourra contenir qu’une seule offre.

API RESTful pour les SI Fournisseurs

Cette API permet en particulier d’alimenter les espaces de travail via des opérations d’imports automatisés (ces espaces de travail vont contenir les jeux de données).

Lorsqu’un utilisateur fait un appel à l’API il est automatiquement authentifié et relié naturellement à une Organisation. Les Organisations n’apparaissent donc pas dans les URL de l’API. 

Une Organisation va contenir un Espace de travail pour la gestion de l’offre de transport.

Les ‘endpoints’ de l’API utilisent l’identifiant de l’espace de travail à impacter. Cette information est disponible dans l’interface IHM du BO Information Voyageur dans le menu Paramétrages > Sécurité .

Open

Cet identifiant est accessible en même temps que les clés d’accès API comme ci-dessous.

Open

Protocole

Les requêtes utilisent les différentes méthodes HTTP : 

• GET pour les consultations (collection ou ressource) 

• POST pour la création de ressource

Toutes les requêtes retournent :

• un code HTTP 200 (OK) : en cas de succès

• un code HTTP 400 (Bad Request) : lorsque des paramètres sont inconnus.  

• un code HTTP 406 (Not Acceptable) : lorsque les données fournies ne permettent de traiter la demande

• un code HTTP 500 (Internal Server Error) : en cas d’erreur indéterminée

Les chapitres suivants ne détailleront que les requêtes avec un code de réponse HTTP 200 apportant une information supplémentaire.

Les URL des requêtes HTTP font apparaître différentes parties variables obligatoires pouvant avoir différents contenus. Ils peuvent ou non appartenir à une liste de valeurs autorisées et sont notées entre { }. 

Exemple : http://mon_domaine/{mes_ressources} : la partie {mes_ressources} nécessite de renseigner une chaîne non vide. 

Sécurité

L’authentification est réalisée en utilisant une “basic authentification” comme définit par la RFC2617. L’appelant doit utiliser :

• le code de son organisation comme utilisateur,

• une clé d’accès d’API associée à son organisation comme mot de passe. 

Tous les accès à l’API se font en HTTPS.

Le code de l’organisation est celui défini dans Sésame. Il se retrouve dans IBOO via le menu Paramétrages > Mon organisation. 

Les clés d’accès d’API sont paramétrables par Ile-de-France Mobilités et les transporteurs dans le BO Offre. Celles définis dans une organisation sont ensuite accessibles des utilisateurs de l’organisation pour qu’ils puissent accéder aux API d’import. Une clé d’accès d’API peut également être communiqué à des personnes tierces pour qu’elles puissent également accéder à ces API.

Exemple d’une requête curl : 

curl --basic --user organisation-code:bae26d4c1a358c7fdaf7b5e1277e5219

Import

Un import se caractérise par : 

Créer un import : 

Méthode http

POST

Url de la requête :

    URL BO Information Voyageur /workbenches/{id}/imports.json

• id : Identifiant de l’espace de travail

La requête POST allant être transmise est une requête « multipart ». 

Les attributs de cette requête sont les suivants : 

• name: nom de l’import [obligatoire]

• file: fichier à importer [obligatoire]

• notification_target: la destination des notifications à la fin de l’import

  • valeurs :

    • workbench tous les utilisateurs de l’espace de travail reçoivent une notification

    • none pas de notification envoyée (défaut)

• options:

  • automatic_merge: booléen permettant de définir si la finalisation s’effectue automatiquement après un import réussi.

  • archive_on_fail : booléen permettant de définir si l’import a échoué d’archiver le jeu de données créé

  • merge_method : chaîne de caractère permettant de définir quelle finalisation utiliser :

    • legacy : finalisation historique

    • experimental : finalisation V2 contenant de nombreuses optimisations

Pour soumettre des attributs dans form-data il faut utiliser la syntaxe workbench_import[attribute name], par exemple workbench_import[name].

Exemple d’une requête curl : 

curl -X POST --basic --user organisation-code:bae26d4c1a358c7fdaf7b5e1277e5219 \

• F "workbench_import[name]=Test" -F "workbench_import[options][automatic_merge]=true" -F "workbench_import[file]=@netex.zip;type=application/zip" \

  https://iboo.iledefrance-mobilites.fr/api/v1/workbenches/218/imports

Attention : Si un jeu de données existe avec le statut “Ready” sur les même lignes et périodes, l’import va échouer avec cette erreur : Le référentiel abc n'a pas pu être créé car un référentiel existe déjà sur les mêmes périodes et lignes: xyz

La solution la plus simple pour débloquer la situation est d’archiver le jeu de données en question sur l’interface d’IBOO

Réponse : 

HTTP 200 (OK) : la demande est acceptée et retourne notamment l’identifiant de l’import et son état

Exemple de réponse : 

Obtenir la liste des imports d’un espace de travail d’une Organisation : 

Méthode http

GET

Url de la requête

    URL BO Information Voyageur /workbenches/{id}/imports.json

• id : Identifiant de l’espace de travail

Exemple d’une requête curl : 

curl -X GET --basic --user organisation-code:bae26d4c1a358c7fdaf7b5e1277e5219 https://iboo.iledefrance-mobilites.fr/api/v1/workbenches/218/imports.json

Réponse : 

    HTTP 200 (OK) : la demande est acceptée et retourne la liste des imports d’un espace de travail 

Exemple de réponse : 

Récupérer un import par son code : 

Méthode http

GET

Url de la requête

    URL BO Information Voyageur /workbenches/{id}/imports/{code_import}.json

• id : Identifiant de l’espace de travail

• code_import : clé permettant d’identifier l’import (id)

Exemple d’une requête curl : 

curl -X GET --basic --user organisation-code:bae26d4c1a358c7fdaf7b5e1277e5219 https://iboo.iledefrance-mobilites.fr/api/v1/workbenches/218/imports/12384984.json

Réponse : 

    HTTP 200 (OK) : la demande est acceptée et retourne le détail d’un import de l’espace de travail avec son identifiant et son état

Exemple :