API publique · prévue · pas construite · aucune clé délivrée pour l'instant

Une API publique est dans nos projets.

Nous prévoyons une interface REST + JSON en lecture seule sur le répertoire public d'organisations, de programmes, d'événements et de projets de CommunATI. Elle n'est pas encore construite et aucune clé n'a été délivrée. Si elle voit le jour, elle pourrait servir à intégrer les fiches STIM du Manitoba sur un portail de division scolaire, alimenter une application de découverte régionale, soutenir la recherche sur l'accès ou nourrir des outils pédagogiques. Tout sur cette page est un projet et peut changer.

Dites-nous que ça vous intéresse Voir les points de terminaison prévus

Feuille de route

Phases prévues, sans date pour l'instant.

Si nous construisons l'API, nous prévoyons le faire par étapes. Aucune de ces phases n'a commencé et aucune n'a de date. Nous mettrons cette page à jour si cela change.

Prévu · Phase 1

Répertoire en lecture seule

Organisations, programmes, événements. JSON uniquement. Authentification par clé d'API statique. 60 requêtes / minute / clé. Points de terminaison bêta versionnés sous /v1beta.

Prévu · Phase 2

v1 + projets

Espace de noms stable /v1, point de terminaison de la galerie de projets, géorecherche, filtres par tranche d'âge, ETags + Last-Modified, schéma OpenAPI 3.1 publié.

Prévu · Phase 3

OAuth 2.0 + webhooks

OAuth 2.0 avec des jetons à portée organisation. Points de terminaison en écriture pour que les organisations membres gèrent leurs propres fiches par programmation. Webhooks sortants pour les nouveaux programmes et les changements d'événements.

Idée · Phase 4

Autres provinces (idée seulement)

Nous pourrions un jour explorer une recherche commune avec des répertoires semblables dans d'autres provinces. Aucune entente n'existe.

Points de terminaison (prévus)

Ressources en lecture seule prévues en premier.

URL de base prévue (pas encore construite) : https://api.communati.ca/v1beta (bêta) → https://api.communati.ca/v1 (stable). Tels que prévus, tous les points de terminaison renverraient application/json, avec application/geo+json sur les points géo via l'en-tête Accept.

GET/organizations

Liste les organisations approuvées. Filtres : region, type, indigenous_led, has_active_programs. Pagination par ?cursor. Renvoie le nom, le slug, la région, lat/long, URL du logo, sommaire, et le nombre de programmes de l'organisation.

Auth : tout palier · Débit : 60/min bêta, 600/min stable · ETag pris en charge

GET/organizations/{slug}

Vue détaillée d'une organisation. Inclut la description complète, les coordonnées, l'URL d'inscription, la liste des programmes (sommaire) et les événements affichés.

Auth : tout palier · Débit : 60/min bêta · Cache-Control : public, max-age=300

GET/programs

Liste les programmes pour toutes les organisations. Filtres : age_band (moins de 5 ans, 5-7, 8-10, 11-13, 14-16, 17+), type (robotique, code, sciences, fabrication, IA, etc.), region, format (présentiel, virtuel, hybride), distance_km + near (lat,long). Renvoie le sommaire du programme et le slug de l'organisation parente.

Auth : tout palier · Débit : 60/min bêta · Prend en charge ?lang=fr pour les descriptions traduites, lorsqu'elles existent

GET/programs/{slug}

Vue détaillée d'un programme. Inclut l'horaire, le lieu, la tranche d'âge, le nom des animateurs (si public), le lien d'inscription, et le nombre de programmes connexes de la même organisation.

Auth : tout palier · Débit : 60/min bêta

GET/events

Événements publics à venir, toutes organisations confondues. Filtres : start_after, start_before, region, age_band, category. Prend en charge format=icalendar pour obtenir un flux .ics au lieu du JSON.

Auth : tout palier · Débit : 60/min bêta · Le format iCalendar reflète events.ics

GET/projects

Galerie de projets publics — projets soumis par les jeunes, approuvés par modération, provenant des organisations membres. Renvoie le titre, le résumé, l'URL de l'image, l'organisation contributrice, les étiquettes et la date de soumission. Aucune donnée personnelle sur les jeunes.

Auth : tout palier · Débit : 60/min bêta · phase ultérieure

GET/sponsors

Liste des commanditaires, si un programme public de commandite existe d'ici là — avec l'URL du logo, le niveau de commandite, et (lorsque le commanditaire l'autorise) une description publique. Exclut tout commanditaire qui refuse la mention publique.

Auth : tout palier · Débit : 60/min bêta · phase ultérieure

POST/organizations/{slug}/programs

Crée ou met à jour un programme appartenant à votre organisation. Requiert un jeton d'accès OAuth 2.0 avec la portée programs:write, délivré à un administrateur d'organisation vérifié.

Auth : OAuth 2.0 (portée organisation) · Débit : 30/min · phase ultérieure

Authentification

Authentification prévue : clés statiques d'abord, OAuth 2.0 ensuite.

Telles que prévues, les clés bêta seraient statiques, propres à chaque développeur ou organisation, et renouvelables sur demande. L'accès en écriture utiliserait OAuth 2.0 avec des jetons à portée organisation, autorisés par l'administrateur de l'organisation. Aucune clé n'existe pour l'instant.

# Exemple seulement, pas encore construit. Bêta prévue : clé d'API statique dans l'en-tête Authorization
curl https://api.communati.ca/v1beta/programs?age_band=8-10&region=winnipeg \
  -H "Authorization: Bearer cmnt_pk_live_xxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

# Stable : OAuth 2.0 client_credentials (serveur à serveur)
curl https://api.communati.ca/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=cmnt_ci_xxxxxxxxxxxx \
  -d client_secret=cmnt_cs_xxxxxxxxxxxx \
  -d scope=programs:read events:read

Tels que prévus, les jetons seraient des JWT signés en ES256, avec des clés publiques publiées à /.well-known/jwks.json si un point de terminaison de production voit le jour. Durées de vie prévues : une heure pour client_credentials, douze heures pour les jetons OAuth 2.0 à portée utilisateur.

Limites de débit et usage équitable

Limites de débit prévues.

Nous prévoyons 60 requêtes par minute par clé en bêta, avec des pointes permises jusqu'à 120 requêtes par minute, et environ 600 requêtes par minute en version stable. Une option à fort volume pourrait suivre (environ 6 000 requêtes par minute); ses conditions et ses niveaux de service ne sont pas décidés.

Telles que prévues, les limites seraient indicatives durant la bêta — un dépassement renverrait HTTP 429 avec un en-tête Retry-After au lieu de bloquer la clé. Un abus soutenu, le moissonnage ou tout comportement qui dégrade le service pour les autres pourrait entraîner la révocation. Les conditions d'utilisation ne sont pas encore rédigées.

Schéma + modèle de données

Schéma prévu : JSON Schema en bêta, OpenAPI 3.1 en stable.

Telle que prévue, la bêta comprendrait des fragments JSON Schema par point de terminaison à /v1beta/_schema/{resource}.json. La version stable publierait un seul openapi.yaml couvrant chaque point public, plus des bibliothèques client générées pour TypeScript, Python et Swift. Le schéma serait versionné indépendamment de l'environnement d'exécution; l'ajout de champs rétrocompatibles ne changerait pas la version majeure.

Tels que prévus, les champs des ressources de base utiliseraient snake_case, les horodatages seraient en ISO 8601 UTC, la latitude et la longitude en degrés décimaux WGS 84, la devise serait uniquement CAD et les codes de langue suivraient BCP 47 (en-CA, fr-CA).

Cas d'usage

Ce qu'une API comme celle-ci pourrait soutenir.

Exemples seulement. Ce sont des illustrations d'usages possibles, pas des partenaires, des utilisateurs ni des engagements. Personne n'a encore accès à l'API.

Si vous pensez utiliser un outil comme celui-ci, écrivez-nous à info@communati.ca. Votre intérêt nous aide à décider s'il faut la construire, et quoi construire.

Votre intérêt

Dites-nous que ça vous intéresse.

Il n'y a pas encore de clés, de bêta ni de bac à sable. Si vous pensez utiliser une API publique de CommunATI, un courriel nous aide à décider s'il faut la construire et quoi construire en premier. Pour tout outil qui toucherait des données d'enfants ou de familles, nous voulons aussi discuter tôt des lois sur la protection des renseignements personnels qui pourraient s’appliquer, par exemple la loi fédérale (LPRPDE) et les lois du Manitoba.

Écrivez à info@communati.ca avec :

Nous vous répondrons quand nous aurons des nouvelles. Nous ne vous ajouterons à aucune liste sans vous le demander.

Questions ouvertes

Là où vos commentaires peuvent orienter l'API.

Quelques décisions de conception API encore ouvertes. Si vous avez une préférence, écrivez-nous à info@communati.ca — ces questions restent ouvertes pendant la planification :

Savoir si l'API voit le jour.

Si nous construisons l'API, nous publierons ici un journal des modifications. D'ici là, écrivez-nous et nous vous aviserons s'il y a du nouveau — court, peu fréquent, sans marketing.

Demander des nouvelles Nous joindre