Parcours · administrateur de la plateforme et intégrateur
Déclarer une API à la passerelle, s'assurer de son scope, la mettre en service, donner un plan au client, puis le laisser créer sa clé et suivre son usage.
Exemplia ouvre l'API de NotionSocle à ses clients, en lecture. Le premier client est le
Cabinet Morel & Associés (tenant cabinet-morel) ; Inès Garnier y intègre l'API.
Côté Hub, il vous faut un compte SUPERADMIN. Le nom d'hôte api.exemplia.example doit déjà
pointer vers le Hub dans le DNS et avoir un certificat : cela se règle dans les écrans DNS et
Certificats, pas dans l'API Manager.
Rejouer tout le parcours dans le Hub
Publier une API, c'est dire à la passerelle : ce qui arrive ici doit aller là, pour les clients qui ont ce droit, à ce prix.
api.exemplia.example et le chemin /notionsocle/v1 ;notionsocle du Hub (hub_container), port 8080, chemin interne
/api — /notionsocle/v1/pages devient l'appel /api/pages ;api:notionsocle:read, que la clé du client doit porter ;Laissez Publier immédiatement ? sur Non : l'API naît en brouillon, la passerelle ne
la sert pas encore. Le Hub l'enregistre (POST /api/apim/admin/apis), recharge la
passerelle et ouvre la fiche.
⚠ La case « Autoriser sans authentification » est ignorée sur le Hub 3.77.0 : une API
publiée exige toujours une clé. Le type minihub n'est pas reconnu par la passerelle.
Le parcours guidé de l'onglet Applications (bouton Publier une API) fait la même chose en créant aussi les scopes et une clé par tenant choisi. Une API créée ici n'apparaît pas dans cet onglet, mais dans APIs publiées.
Faire cette étape dans le Hub → Pour aller plus loin : apim.apinew.public_hostname apim.apinew.required_scope apim.apinew.allow_no_auth apim.apinew.statut apim.apinew.creer apim.apps.publier
Un scope est un droit nommé, de la forme api:<slug>:<verbe>. L'API en exige un ; la clé
du client en porte une liste. api:notionsocle:* couvre read, write et admin.
Cherchez api:notionsocle:read dans le catalogue. Il compte : au portail développeur, le
client ne peut mettre dans sa clé que des scopes actifs de ce catalogue.
⚠ Une API déclarée à la main ne crée pas ses scopes sur le Hub 3.77.0 : seuls le parcours
guidé et la route POST /api/apim/admin/scopes/auto-generate/{id} (avec api_slug) créent
les quatre scopes read, write, admin et *. L'écran n'a pas de bouton pour créer un
scope.
Les colonnes APIs et Keys sont des compteurs gardés en base, recalculés au démarrage du Hub et par 🔄 Recompute stats : cliquez avant de les lire.
Faire cette étape dans le Hub → Pour aller plus loin : apim.scopes.ecran apim.scopes.recompute portal.apim.keys.creer.scopes
Sur la fiche de l'API, onglet Identité, bloc Modifier : passez le statut de draft à
published. La passerelle recharge son catalogue ; l'effet est immédiat. En haut à droite,
l'URL publique donne l'adresse exacte que les clients appelleront.
L'écran montré ici est la fiche d'une autre API (n° 4) : celle de NotionSocle est la même page.
⚠ Recochez ScanGuard. La case s'affiche décochée, quelle que soit la valeur actuelle, et le formulaire l'envoie toujours : appliquer un changement de statut sans la recocher désactive le filtre anti-attaques de l'API.
⚠ Sur le Hub 3.77.0, plusieurs valeurs de la fiche arrivent vides (application cible, port, chemin interne), et 🩺 Tester la connectivité répond toujours « non implémenté ».
Faire cette étape dans le Hub → Pour aller plus loin : apim.apidetail.statut apim.apidetail.scan_guard apim.apidetail.appliquer apim.apidetail.tester
Le plan APIM fixe ce que paie un client chaque mois pour accéder aux API, en plus de ce
qu'il consomme. À la facturation, le Hub additionne le prix du plan et la consommation du
mois. Il est distinct du plan commercial d'IAM (free, pro…).
Ouvrez + Nouveau plan, saisissez le slug notionsocle-pro, le nom et le prix mensuel en
centimes (4900 pour 49,00), puis Créer. Le plan est actif aussitôt et proposé sur la
fiche de chaque tenant.
⚠ Les quotas affichés sur les cartes ne se créent pas depuis le Hub, et la passerelle ne
les applique pas : les plafonds effectifs viennent des débits de l'API et des règles JDM
apim_quota.
Faire cette étape dans le Hub → Pour aller plus loin : apim.plans.ecran apim.plans.mensuel apim.plans.creer
L'API Manager ne crée pas ses propres clients : ce sont les tenants d'IAM. Dans API Manager
› Tenants, ouvrez Détail sur la ligne de cabinet-morel. L'adresse de la fiche porte
le numéro du tenant, pas son slug.
L'écran montré ici est la fiche d'un autre tenant (n° 284) : celle du Cabinet Morel est la même page.
Choisissez NotionSocle Pro, puis Attacher. Le Hub clôt le plan en cours et ouvre une nouvelle période ; l'historique garde les plans précédents.
⚠ Les deux écritures ne sont pas dans une transaction : si la seconde échoue, le tenant reste sans plan en cours. Dans la liste des tenants, la colonne Plan APIM montre un nom de plan même quand aucun n'est attaché : seule la fiche dit « — aucun — ».
Cette fiche permet aussi d'émettre une clé au nom du client (+ Nouvelle clé). ⚠ Le scope
proposé, api:*, ouvre toutes les API du Hub : remplacez-le par api:notionsocle:read.
Faire cette étape dans le Hub → Pour aller plus loin : apim.tenants.ecran apim.tenants.col.plan apim.tenantdetail.plan.attacher apim.tenantdetail.cles.nouvelle
On passe du côté du client. Inès Garnier ouvre le portail développeur de son tenant, onglet APIs disponibles. La carte de NotionSocle donne :
https://api.exemplia.example/notionsocle/v1 ;api:notionsocle:read — la valeur à mettre dans la clé ;⚠ Sur le Hub 3.77.0, le catalogue liste toutes les API publiées, pas seulement celles que les clés du tenant ouvrent, et chaque carte porte « Auth requise ».
Faire cette étape dans le Hub → Pour aller plus loin : portal.apim.apis.ecran portal.apim.apis.cartes
Dans Mes clés, + Nouvelle clé ouvre le formulaire. Inès saisit :
prod-cabinet-morel ;api:notionsocle:read, et rien de plus ;Créer affiche la clé brute dans la fenêtre « Conservez cette clé immédiatement ». Le Hub n'en garde que l'empreinte SHA-256 : une fois la fenêtre fermée, personne ne peut la réafficher. Elle se range dans un coffre à secrets, jamais dans le code.
⚠ Un scope absent du catalogue de l'étape 2 est refusé : « Erreur : scope_not_allowed ».
⚠ Une clé révoquée depuis le portail reste acceptée jusqu'à 60 secondes sur le Hub 3.77.0, le temps que le cache de la passerelle expire.
Faire cette étape dans le Hub → Pour aller plus loin : portal.apim.keys.ecran portal.apim.keys.creer.nom portal.apim.keys.creer.scopes portal.apim.keys.creer.ips portal.apim.keys.creer.expire portal.apim.keys.creer.valider
Le programme du client envoie la clé dans l'en-tête X-API-Key (ou Authorization: Bearer) :
curl -H "X-API-Key: apim_DEMO00000000000000000000000000000000000000000" \
https://api.exemplia.example/notionsocle/v1/…
La passerelle vérifie la clé et son scope, puis transmet l'appel à NotionSocle sans la
clé. Elle dit à l'application qui appelle par ses propres en-têtes : X-APIM-Tenant-Id,
X-APIM-User-Id, X-APIM-Scopes, X-APIM-Plan…
Mon usage montre les appels depuis le 1er du mois, les réussis, les échecs (codes 400 et plus : clé révoquée, scope manquant, quota dépassé ; ou 500 et plus : l'API répond mal) et le coût à l'usage. Le forfait du plan s'y ajoute sur la facture. Les chiffres ne se rafraîchissent pas seuls : Rafraîchir les redemande.
⚠ L'encadré « Headers HTTP » de la fiche de l'API annonce des noms d'en-têtes que la passerelle n'envoie pas, et ses extraits de code refusent chaque appel s'ils sont copiés tels quels. Fiez-vous à la liste ci-dessus.
Faire cette étape dans le Hub → Pour aller plus loin : portal.apim.keys.creer.valider apim.apidetail.entetes portal.apim.usage.ecran portal.apim.usage.kpi_erreurs portal.apim.usage.kpi_cout
https://api.exemplia.example/notionsocle/v1, protégée par
le scope api:notionsocle:read et filtrée par ScanGuard ;scope_not_allowed).api:* : il ouvre toutes
les API du Hub.