Référence de l’API publique Hubigo

Cette référence aide l’équipe TI de la municipalité à déterminer quelles données municipales peuvent être lues et quelles opérations exigent une autorisation. L’API donne surtout accès aux contenus publiés sur le portail citoyen. Certaines ressources intersystèmes, dites B2B, et certaines données personnelles ont des règles d’accès distinctes. Les schémas complets figurent dans le contrat OpenAPI, sur le portail technique.

Fonctionnement général

Les requêtes sont envoyées en HTTPS. L’API répond en JSON encodé en UTF-8. Chaque installation Hubigo utilise un domaine d’API qui lui est associé; l’adresse d’une instance dédiée est communiquée lors de sa mise en service.

URL de base
https://api-core.hubigo.ca

Premier appel

1. Dans Administration → Paramètres → API, créer une clé adaptée au système à connecter. 2. La conserver dans un gestionnaire de secrets. 3. L’envoyer dans l’en-tête X-API-Key. 4. Vérifier le code HTTP et le corps JSON retournés.

# Avis publics actifs
GET https://api-core.hubigo.ca/public-api-notices?status=active&limit=50
X-API-Key: hbg_…

# Réponse (extrait)
{ "data": [ { "id": "…", "title": "Avis d’ébullition, secteur nord", "status": "active" } ] }

Gestion des clés

Chaque appel transmet une clé dans l’en-tête X-API-Key. Le type est choisi selon la portée nécessaire :

Les clés sont créées et révoquées dans Administration → Paramètres → API. Une ressource public peut accepter un appel sans clé; une clé permet toutefois d’associer l’usage à l’intégration. Les ressources B2B et PII exigent une clé.

X-API-Key: hbg_xxxxxxxxxxxxxxxxxxxx

Signature HMAC des requêtes

HMAC permet au serveur de vérifier qu’une requête n’a pas été modifiée. Si un secret de signature est associé à la clé, la signature de chaque requête est calculée et transmise dans X-Hubigo-Signature.

X-Hubigo-Signature: t=<unix>,v1=<hex>
# v1 = HMAC-SHA256(secret, "<t>.<corps_brut>")
# fenêtre de validité : 5 minutes

Formats de données

Les chemins et paramètres sont en anglais, par exemple status, limit et format. Le format GeoJSON est demandé avec ?format=geojson pour les ressources géographiques compatibles. Le domaine des loisirs propose aussi un flux iCal. Les opérations d’écriture documentées ci-dessous se trouvent dans le domaine Organismes.

Niveaux d’accès

Chaque point d’accès indique dans le contrat OpenAPI le niveau de données qu’il expose :

Cette API ne documente ni export général des citoyens, ni notes internes, ni secrets. Les appels peuvent être journalisés et certaines ressources, notamment les avis et la facturation, sont soumises à des quotas.

Traitement des erreurs

{
  "error": {
    "code": "platform_key_required",
    "message": "Cette famille exige une clé plateforme."
  }
}

Limites de requêtes

Les limites sont appliquées par clé. Après une réponse 429, attendre la durée indiquée par Retry-After, puis espacer progressivement les nouvelles tentatives. Les avis et la facturation peuvent avoir des seuils plus restrictifs.

Communications

Avis publics, messages, catégories d’alerte, niveaux d’urgence et zones affectées.

Services aux citoyens

Catalogue des types de demande, référentiels de formulaire, statistiques agrégées et suivi d’une demande par jeton.

Loisirs

Catalogue d’activités, camps de jour, événements et plateaux réservables, plus un flux iCal public.

Organismes

La seule famille en écriture : synchronisation des organismes et de leurs réservations de plateaux avec les systèmes de la ville.

Participation

Consultations publiques et résultats agrégés, lorsque la ville les publie.

Abonnements

Vérification de l’accès d’un citoyen à un service (éco-centre, bibliothèque, borne). Endpoints à données personnelles : clé requise.

Administration ville

Socle partagé : métadonnées de la ville, zones, lieux, sondes de disponibilité, pages légales et lookup cadastral.

Facturation plateforme

Usage, limites et alertes agrégés sur l’ensemble des villes. Réservé aux clés plateforme Hubigo (hbg_pk_…).

La validation d’une intégration s’appuie sur les paramètres, les schémas JSON et les exemples du contrat OpenAPI, dans le portail technique.