API Gateway Présentation générale

Le constitueCHAMPREPAPI Gateway le point d’entrée public pour les intégrations de plateformes prises en charge. Il valide les identifiants, vérifie les périmètres et l’accès aux services, applique les contrôles d’utilisation en vigueur et achemine les requêtes acceptées vers le CHAMPREPservice concerné.

URL de base

https://api.champrep.com/v1

Les routes publiques sélectionnées sont gérées par version sous /v1. Utilisez l’URL HTTPS complète dans les applications serveur et privilégiez la configuration d’environnement plutôt que de disséminer l’URL de base dans l’ensemble de votre code.

Première requête authentifiée

Créez une clé à portée limitée dans API Clés, puis transmettez-la en tant qu’ identifiant « bearer » :

curl --fail-with-body \
  --header "Authorization: Bearer $CHAMPREP_TOKEN" \
  --header "Accept: application/json" \
  https://api.champrep.com/v1/auth/whoami

Ne placez jamais une clé réelle dans le contrôle de version, un bundle de navigateur, un binaire mobile, un message d’assistance ou la documentation. Utilisez un gestionnaire de secrets côté serveur pour les intégrations déployées.

Conventions relatives aux requêtes

• Envoyez et acceptez des données au format JSON, sauf si un point de terminaison spécifie explicitement un autre type de média.
• Utilisez des horodatages ISO 8601 avec un fuseau horaire explicite pour les valeurs de date et d’heure.
• Encodez les valeurs du chemin et de la requête au format URL.
• Conservez l’identifiant « bearer » dans l’ Authorization en-tête.
• Traitez les identifiants comme des chaînes opaques ; n’en déduisez pas le format et ne les construisez pas localement.
• Utilisez les /v1 les routes dans le Référence des points de terminaison de service.

Les utilisateurs officiels peuventSDKs utiliser les routes de compatibilité Gateway pendant la migration d’un service vers une offre sélectionnée /v1 . Cette couche de compatibilité est destinée à SDK; les nouvelles intégrations directes ne doivent pas copier les chemins d’accès privés du backend à partir du trafic du navigateur ou des composants SDKinternes.

Enveloppes de réponse

Les réponses générées avec succès par la passerelle se présentent sous la forme suivante :

{
  "success": true,
  "data": {}
}

Les erreurs de passerelle se présentent sous la forme suivante :

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "A safe explanation of the error.",
    "status": 400
  }
}

Certaines réponses de services transitant par un proxy conservent leur enveloppe de données spécifique au service. Vérifiez toujours le statut HTTP en premier lieu, puis lisez success, data, ou error lorsqu’elle est disponible. Voir erreurs, limites et tentatives de réessai pour une gestion portable des erreurs.

Flux d’authentification et d’autorisation

Chaque demande de service est évaluée dans l’ordre suivant :

1. La passerelle valide la cléAPI ainsi que toutes les restrictions IP configurées.
2. La fenêtre d’utilisation actuelle de la passerelle est cochée.
3. API Gateway est vérifié pour le forfait et le profil actifs.
4. L’accès au service de destination est vérifié.
5. La portée de la clé est comparée à la route et à la méthode HTTP.
6. Le service de destination applique ses propres vérifications relatives aux rôles, à l’organisation, aux ressources et aux quotas.

A 403 peut donc indiquer que la clé est valide, mais que le périmètre actif, le rôle, l’accès au service, le forfait, la politique de l’organisation ou l’autorisation relative à la ressource ne permettent pas l’opération.

Gestion des versions

Le premier segment de l’URL correspond à la versionAPI majeure. Des champs de réponse supplémentaires et de nouveaux points de terminaison peuvent apparaître au sein d’une même version majeure. Les intégrations doivent ignorer les champs inconnus et ne doivent pas se fier à des champs non documentés ni à leur ordre d’apparition.

Utilisation GET /v1/version pour obtenir des informations sur la version publique de la passerelle. Prévoyez explicitement les migrations vers une future version majeure plutôt que de réécrire /v1 à l’exécution.

Étapes suivantes

• Créer une clé à privilèges minimaux.
• Choisissez un itinéraire de service.
• Gérer les limites et les erreurs.
• Utilisez des webhooks plutôt que des interrogations fréquentes.
• Vous préférez les workflows en terminal ? Installez la CHAMPREPCLI.