Les points de lecture de contenus événementiels en question dans cette migration sont:

  • L'export JSON: Nous appelons ici "export JSON" le lien qui était donné sur le menu d'export des agendas agenda sur https://openagenda.com pour lire le contenu d'un agenda au format JSON. Il prend la forme suivante: https://openagenda.com/agendas/{agendaUID}/events.json et est documenté ici: https://developers.openagenda.com/export-json-dun-agenda/
  • Lecture API v2: Le point de lecture des événements d'un agenda via l'API v2 documentée sur cette page https://developers.openagenda.com/10-lecture/ et prend la forme https://api.openagenda.com/v2/agendas/{agendaUID}/events

Les éléments à prendre en compte lors d'une mise à jour d'un script de synchronisation ou d'une application web utilisant l'export JSON pour la faire utiliser une lecture sur l'API v2 se déclinent en trois volets, détaillés dans les sections suivantes.

Les filtres

L'export JSON rassemble tous les filtres dans une clé de requête oaq. Les filtres de l'API de lecture v2 se mettent directement au premier niveau.

Important: par défaut, l'export JSON ne présente que les événements à venir, triés du plus proche au plus lointain dans le temps. Sur l'API v2, tous les événements publiés sont présentés, en premier ceux à venir du plus proche du temps présent au plus lointain suivi des passés du plus proche du présent au plus lointain. Pour limiter la sélection sur l'API v2 aux événements présents et à venirs, le filtre suivant doit être utilisé: ?relative[]=ongoing&relative[]=upcoming

Par exemple, une requête délimitant les événements qui se déroulent sur une journée précise sont ciblées de la manière suivante sur l'export JSON:

https://openagenda.com/agendas/{agendaUid}/events.json?oaq[from]=2021-02-07

... et de la manière suivante sur l'API v2:

https://api.openagenda.com/v2/agendas/{agendaUid}/events?timings[gte]=2022-02-01T23:00:00.000Z&timings[lte]=2022-02-02T22:59:59.999Z

Il y a de petites variations pour chaque filtres, documentés dans les pages données en tête d'article. Le principal changement concerne le remplacement de la notion de tag sur openagenda.com par la notion de champ additionnels: sur l'export JSON, la clé oaq[tags] est utilisée pour filtrer sur une valeur provenant d'un champ à choix sur le formulaire événement de l'agenda correspondant. Sur l'API v2, la clé a utiliser est celle du champ même, donnée dans la configuration de l'agenda (documenté ici: https://developers.openagenda.com/configuration-dun-agenda/). Les valeurs à préciser ne sont plus les codes de tags mais les identifiants. Ainsi, le filtre suivant sur l'export JSON:

https://openagenda.com/agendas/{agendaUID}/events.json?oaq[tags][]=atelier&key=VOTRECLE

... devient sur l'API v2:

https://api.openagenda.com/v2/agendas/{agendaUID}/events?categories-metropolitaines[]=3&key=VOTRECLE

La navigation

Dans les deux cas, les résultats sont paginés. Dans le cas de l'export JSON, seule une navigation qui utilise les clés ?offset et &limit est possible.

L'equivalence sur l'API v2 est retrouvée en utilisant les clés ?from et &size

Important: pour la lecture de programmations entières, l'API v2 propose une clé after à utiliser dans le cadre d'une boucle de lecture. Il faut éviter de boucler sur un grand nombre d'itérationsavec la clé from. Plus la valeur from sera importante, moins la requête sera performante. Les trop grandes valeurs de from peuvent être bloquées.

Les contenus

Par défaut, seuls certains champs sont présentés sur l'API. Pour avoir le détail des horaires ainsi que les champs additionnels, il faudra rajouter un ?detailed=1 à la requête.

Les évolutions sur les champs suivants sont à prendre en compte.

Champ image

Sur l'export JSON, les images étaient présentée en premier niveau derrière les clés image, thumbnail et originalImage

Désormais, les données image sont présentées sous une unique clé image, tel que documenté ici: https://developers.openagenda.com/00-structure-evenement/#image

Liste des plages horaires

Sur l'export, une liste d'items avec clés { start, end } est donnée derrière la clé timings, dont les valeurs sont calées sur le fuseau UTC.

Sur l'API, la clé start est remplacée par une clé begin. Les horaires sont donnés dans le fuseau local.

Par exemple, une donnée start d'un premier item de la liste timings de l'export JSON avec pour valeur 2022-02-07T09:00:00.000Z sera présentée sous la clé begin dans l'API avec la valeur 2022-02-07T10:00:00+0100

Les tags et les champs custom

Les tags & champs custom de l'export JSON sont présentés sous 3 clés: tags et tagGroups pour les tags, custom pour les données particulières aux agendas.

Sur OpenAgenda, les tags et champs custom sont désormais intégrés dans une notion de champs additionnels. Les codes tags, tagGroups ou custom de l'export JSON ne sont pas repris sur l'API v2. Les valeurs de chaque champ additionnel sont présentées sous des clés propres à chaque champ. Ces clés, ainsi que les identifiants des sélections proposées par les champs additionnels à choix sont listées dans la configuration de l'agenda (voir https://developers.openagenda.com/configuration-dun-agenda/)

La description longue

L'export JSON décline la description longue sous deux clés: longDescription et html. Une option (include_embedded) permet de remplacer les liens pointant vers des contenus multimedias par leurs équivalent "embeds".

L'API ne présente plus que le champ longDescription, son format peut être controlé par le paramètre longDescriptionFormat tel que détaillé ici: https://developers.openagenda.com/10-lecture/

Les lieux

Toutes les données relatives au lieu où se déroule l'événement se trouvent désormais sous la clé location

A noter: il est désormais possible de définir des événements en ligne sur OpenAgenda. Dans ce cas, la saisie du lieu devient optionnelle.

Aménagements à l'accessibilité

La structure de la donnée sous la clé accessibility liste désormais toutes les types possibles sous la forme d'un objet. Exemple

{
  ...
  "accessibility":{"ii":false,"hi":false,"vi":false,"pi":false,"mi":true}
  ...
}

Autres

  • origin se nomme désormais originAgenda. Cette donnée décrit l'agenda dans lequel l'événement a été saisi. Vient s'ajouter sourceAgenda, qui fait référence à l'agenda d'où est remonté l'événement, en cas d'un ajout automatique depuis l'une des sources de l'agenda.