Liste publique Capgo API : référence complète pour les développeurs

Vous utilisez probablement un pipeline de déploiement qui fonctionne manuellement, mais qui devient fragile dès que l'équipe a besoin de releases reproductibles. Un développeur crée un bundle, l'envoie depuis un ordinateur, vérifie un dashboard, change un canal, puis attend les données d'adoption. Ce processus peut suffire pour un petit projet, mais il crée des risques évitables lorsque plusieurs apps, environnements et jobs de déploiement partagent la même infrastructure.

Une liste API publique utile doit répondre à plus que « quels endpoints existent ? ». Elle doit montrer comment l'authentification, les identifiants de ressources, l'état de la release, les quotas, les headers, les retries et les workflows par lots s'articulent. Ce guide aborde l'Capgo API sous cet angle opérationnel, avec des patterns applicables aux équipes Capacitor qui construisent une automatisation CI/CD plutôt que des requêtes de test isolées.

Table des matières

• Comprendre l'authentification API Capgo
  • Séparer l'identité de l'autorisation
• Générer vos identifiants API
  • Créer une clé avec un usage précis
  • Rotation sans interruption de service
• Endpoints principaux pour la gestion d'app
  • Concevoir un workflow basé sur l'identifiant
• Création et gestion des releases
  • Préparer le payload de la release
  • Sécuriser les tentatives de retry
• Stratégie de canaux et modèles de rollout
• Endpoints de monitoring et de diagnostic
  • Requêter précisément avant l'agrégation
  • Connecter les diagnostics à l'automatisation
• Rate limiting et headers de sécurité
  • Sécurisez la surface de gestion
• Dépanner les erreurs API courantes
  • Échecs d'authentification
  • Corps de requête invalides
  • Throttling et mutations ambiguës

Comprendre l'authentification Capgo API

L'erreur d'intégration la plus courante est d'envoyer une requête valide avec un mauvais format d'identifiant. Une clé copiée depuis un dashboard n'est pas automatiquement un bearer token, et un bearer token n'est pas utile si la requête omet le Authorization header ou l'envoie sous un mauvais schéma. Le serveur renvoie alors un échec d'authentification avant même d'évaluer l'endpoint, le payload ou l'identifiant de l'app.

Commencez par identifier le nom de l'identifiant utilisé dans la documentation Capgo API actuelle, puis reproduisez exactement l'exemple de requête. Dans une requête classique avec bearer token, le header d'autorisation suit ce modèle :

Authorization: Bearer YOUR_TOKEN

Conservez l'identifiant dans une variable d'environnement lors de vos tests locaux. En CI/CD, injectez-le via le gestionnaire de secrets de la plateforme plutôt que de le committer dans un repo, de l'inclure dans un bundle mobile ou de l'ajouter à une query string. Une application mobile ne doit jamais contenir d'identifiant de gestion, car tout ce qui est déployé sur un appareil peut finir par être inspecté.

Séparez l'identité de l'autorisation

L'authentification détermine qui effectue la requête. L'autorisation détermine ce que cette identité peut modifier. Considérez ces deux vérifications comme distinctes lors de la conception d'un service de déploiement.

Une clé personnelle peut être pratique pour l'exploration, mais elle lie l'automatisation de la production au compte d'une seule personne. Une clé gérée par l'équipe est plus appropriée pour un pipeline partagé, à condition que l'organisation puisse la révoquer et la remplacer sans interrompre les autres tâches. Utilisez des identifiants distincts pour les workflows de développement, de staging et de production lorsque le dashboard et le modèle de permissions permettent cette séparation.

Avant d'appeler un endpoint de release, testez une opération de lecture à faible risque. Confirmez que :

• L'hôte est correct : Utilisez l'URL de base API documentée pour l'environnement actif.
• L'en-tête est complet : Incluez le schéma d'autorisation requis et un Accept en-tête pour les réponses JSON.
• Le corps est encodé correctement : Envoyez-le Content-Type: application/json uniquement lorsque la requête contient du JSON.
• Le scope est suffisant : Un identifiant capable de lire les métadonnées de l'app peut ne pas être autorisé à créer ou distribuer une release.
• La réponse est journalisée de façon sécurisée : Enregistrez les codes d'état et les identifiants de requête, mais masquez les clés, les tokens, le contenu des bundles et les données sensibles de l'appareil.

Les catalogues API publics sont passés de simples répertoires à de véritables outils de découverte opérationnelle. Le récit historique de ProgrammableWeb décrit un répertoire qui a dépassé les 19 000 API en janvier 2018, after 2 294 nouvelles API en 2017 et une moyenne de plus de 2 000 ajouts par an depuis janvier 2014. Cet historique explique pourquoi une liste API publique moderne doit aider les ingénieurs à évaluer le comportement d'intégration, et pas seulement à trouver une URL.

Pour les considérations liées au contrôle d'accès côté client, consultez les modèles d'autorisation d'application CapgoLa même discipline s'applique ici : conservez les identifiants de gestion sur des serveurs de confiance, définissez les permissions de manière délibérée et facilitez le diagnostic des échecs d'autorisation.

Générer vos identifiants API

La création d'identifiants doit être traitée comme un changement de gestion d'accès, et non comme une simple étape de configuration. Les libellés du dashboard peuvent varier ; référez-vous donc à l'interface et à la documentation Capgo actuelles, mais le workflow reste identique.

Créer une clé avec un usage précis

Accédez aux paramètres de l'organisation ou du compte, localisez l'écran API ou des identifiants développeur, et choisissez l'action pour créer une clé. Donnez à la clé un nom qui identifie sa fonction, comme un pipeline de déploiement staging ou un worker de release de production. Évitez les noms basés uniquement sur l'identité d'une personne, car la propriété devient floue lors d'un changement d'équipe.

Sélectionnez les permissions les plus restreintes possibles pour ce workflow. Une tâche qui ne fait que lire le statut de déploiement ne devrait pas avoir la permission de supprimer des applications ou de modifier des canaux. Si l'interface propose un scope au niveau de l'organisation et au niveau de l'application, privilégiez la limite la plus étroite qui permet d'accomplir la tâche.

Copiez le secret dès que le dashboard l'affiche. De nombreux systèmes d'identifiants n'affichent la valeur complète que lors de la création. Stockez-la dans votre gestionnaire de secrets CI/CD, puis testez la récupération dans le pipeline sans afficher la valeur en clair. Un local .env un fichier peut aider lors du développement, mais il doit être exclu du versionnage et ne doit jamais être inclus dans un répertoire web Capacitor.

Rotate without creating an outage

Maintenez une période de chevauchement lors de la rotation d'un identifiant. Ajoutez le remplaçant au gestionnaire de secrets, déployez la configuration du pipeline qui l'utilise, effectuez une lecture authentifiée sans risque, et seulement ensuite, révoquez l'ancienne clé. Si le service supporte plusieurs clés actives, conservez l'ancienne valeur jusqu'à ce que chaque worker et tâche planifiée ait migré.

Pour une équipe, enregistrez le propriétaire de la clé, l'usage, l'environnement, la date de création et la procédure de révocation dans un registre d'accès interne. Ne placez pas le secret lui-même dans ce registre. Cela rend la réponse aux incidents pratique sans transformer la documentation en un nouveau dépôt de secrets.

Le Normes API du gouvernement britannique recommandent de concevoir un document OpenAPI tôt, de valider les entrées, de rejeter les attributs inconnus, d'utiliser TLS 1.2 ou supérieur, et d'appliquer OAuth 2.0 pour le contrôle d'accès. Ces principes sont utiles même lorsque l'intégration utilise des clés API : définissez le contrat avant de construire l'automatisation, rejetez les entrées inattendues et traitez la sécurité du transport comme essentielle.

Pour les modèles de stockage et de rotation de pipeline, utilisez Capgo : conseils sur la gestion des secrets dans les pipelines CI/CD.

Endpoints principaux pour la gestion d'app

La gestion des applications est le plan de contrôle de tout le reste. La création de releases, l'assignation de canaux, la distribution de bundles et les diagnostics nécessitent tous un identifiant d'application stable. L'erreur classique consiste à transmettre un nom d'application lisible par l'humain à chaque tâche en supposant qu'il restera unique. Résolvez l'application une seule fois, persistez l'identifiant canonique, et utilisez cet identifiant pour toutes les opérations suivantes.

Une intégration en production doit modéliser le cycle de vie de l'app autour de quatre capacités :

N'inventez pas de chemins d'endpoints à partir d'un article de blog ou d'un ancien SDK. Lisez la définition actuelle lisible par machine et générez un client typé ou un wrapper de requête à partir de ce contrat. L' Spécification OpenAPI décrit un format indépendant du langage de programmation pour les API HTTP, permettant aux personnes et aux outils de découvrir les endpoints, l'authentification, les schémas de requête, les réponses et le comportement sans inspecter le code source ou le trafic réseau.

Construire un workflow basé sur l'identifiant

Un worker de déploiement doit effectuer une lecture avant d'effectuer une mutation :

1. Résoudre le contexte de l'organisation et de l'application.
2. Récupérer l'enregistrement de l'app et confirmer qu'il appartient au compte attendu.
3. Comparer la plateforme et l'environnement prévus avec la configuration retournée.
4. Stocker l'identifiant canonique de l'app dans l'état du job.
5. Soumettre la release ou le changement de configuration en utilisant cet identifiant.
6. Persistez l'identifiant de réponse pour le polling et le diagnostic ultérieurs.

Cette séquence évite une classe d'erreurs particulièrement coûteuse, où une clé valide met à jour la mauvaise application parce qu'une variable de pipeline pointe vers un ancien projet. Ajoutez une assertion d'environnement explicite, comme exiger qu'un job de staging cible l'application de staging, avant d'autoriser une écriture.

Utilisez des schémas de réponse plutôt qu'un accès JSON libre. Si API renvoie un objet app avec des champs identifier, name, status et configuration, validez les champs nécessaires à votre job et tolérez les ajouts non liés. Rejeter les attributs de requête inconnus vous protège de l'envoi accidentel de clés de configuration mal orthographiées, tandis qu'un parsing de réponse tolérant aide le client à survivre à une extension de réponse non bloquante.

Pour la conception du rollback, séparez l'identité de l'app de l'identité de la release. Documentation sur le versioning et le rollback de Capgo est la référence opérationnelle pertinente. Un rollback doit sélectionner un état de release ou de canal connu pour être stable, et non recréer une configuration d'application de mémoire.

Créer et gérer les releases

Une release de production peut échouer après un upload réussi. L'artifact peut être stocké correctement alors que le traitement reste incomplet, l'assignation au canal n'a pas eu lieu, ou les appareils éligibles n'ont pas reçu la mise à jour. Traitez le workflow comme une séquence de changements d'état observables, avec un identifiant durable et un plan de retry pour chaque opération.

Préparer le payload de la release

Utilisez le schéma Capgo actuel pour les noms de propriétés, les chemins de requête et les champs obligatoires. Un corps de requête copié depuis un endpoint au nom similaire peut être accepté partiellement ou rejeté pour une raison inattendue. Concrètement, la charge utile contient trois zones :

• Identité de l'application : L'identifiant de l'application renvoyé par l'opération de control-plane concernée.
• Métadonnées de la release : La version, l'identité du bundle, le contexte de build et les informations de compatibilité attendus par API.
• Intention de distribution : Le canal ou le contexte de déploiement progressif, lorsque l'opération de release le permet.

Validez le bundle avant de l'envoyer. Vérifiez que le build Capacitor contient les assets web attendus, que sa version correspond aux métadonnées de la CI et que le job ne lit pas un fichier en cours d'écriture. Calculez un checksum local lorsque API en accepte un. Conservez l'URL du build, la référence du commit et l'identifiant de release émis par le serveur dans l'enregistrement de déploiement pour que les jobs suivants puissent corréler les événements d'upload, de traitement et de distribution.

Une séquence fiable est la suivante :

1. Compiler l'application dans un espace de travail propre.
2. Exécutez des tests unitaires, d'intégration et spécifiques à la plateforme.
3. Créer ou envoyer le bundle via l'opération de release documentée.
4. Interrogez la ressource de l'opération ou de la release jusqu'à ce qu'elle atteigne un état final.
5. Associez la release terminée au canal prévu.
6. Vérifiez les signaux d'adoption et d'échec avant la promotion.

Une réponse d'upload confirme l'acceptation par le service, pas la livraison aux utilisateurs. Le statut de traitement, l'éligibilité de l'appareil, la connectivité et l'appartenance au canal déterminent toujours si une mise à jour atteint un appareil.

Rendre les tentatives de réessai sûres

Un timeout ne permet pas de savoir si le serveur a rejeté la requête ou l'a terminée avant l'échec de la connexion. Renvoyer la même release peut donc créer des doublons ou des versions conflictuelles. Utilisez une clé d'idempotence quand Capgo en supporte une. Sans cette option, interrogez via les métadonnées de la release ou un identifiant de build généré par le client avant de retenter une mutation.

Les uploads en batch nécessitent un état par élément. Placez chaque variante d'app dans une file d'attente durable et enregistrez son résultat indépendamment. Un retry de worker ne devrait sélectionner que les éléments non terminés, plutôt que de rejouer tout le batch après un échec. Si un endpoint de masse est disponible, vérifiez si sa réponse inclut un résultat pour chaque élément. Un statut de succès global peut masquer une variante échouée, tandis qu'une erreur globale peut occulter un travail terminé.

Règle opérationnelle : Stockez immédiatement l'identifiant de release du serveur, puis utilisez cet identifiant pour les vérifications de traitement, l'assignation au canal et les diagnostics.

Les limites de débit affectent l'upload et le polling. Guide sur le rate-limiting de API notez que les quotas doivent refléter l'action effectuée et que les clients ont besoin d'headers exploitables et d'un comportement de retry. Appliquez un traitement distinct pour la création de release, le polling de statut, les recherches et les mutations sensibles. Une boucle de polling qui effectue des retries à la vitesse de l'upload peut consommer le quota nécessaire à une action corrective.

Lisez les headers de rate-limit lorsqu'ils sont retournés, respectez l'intervalle de retry fourni par le serveur et utilisez des délais croissants en leur absence. Ajoutez du jitter pour éviter que plusieurs workers CI ne fassent des retries simultanément. Limitez le polling, arrêtez-vous à un état terminal et incluez le corps de la réponse finale dans les logs de la CI après avoir supprimé les identifiants et les tokens. Si quelqu'un annule un déploiement, enregistrez l'acteur ou le job d'automatisation, l'état actuel de la release et si l'artifact reste disponible pour un retry ultérieur.

Stratégie de canaux et modèles de déploiement

La conception des canaux est une décision de gouvernance des releases, pas un simple exercice de nommage. Les canaux staging, beta et production s'adressent à des audiences différentes et doivent avoir des règles de promotion distinctes. Le bon choix dépend de l'incertitude résiduelle dans le bundle et de la rapidité avec laquelle l'équipe a besoin de feedback.

Un canal de staging doit être déterministe. Assignez des appareils ou comptes de test connus, protégez le canal contre les changements accidentels, et faites en sorte que la CI ne promeuve la version qu'après la réussite des tests requis. Le mode Beta est utile quand le trafic proche de la production est important, mais il nécessite une définition claire de l'audience et un processus de support pour signaler les erreurs. La production doit être routinière : la release a passé les étapes précédentes, la cible de rollback est connue et le monitoring est déjà connecté.

Le workflow API doit refléter ces limites. Un pipeline peut créer la release une seule fois, l'assigner au staging, puis promouvoir le même objet de release après validation. Recompiler entre les canaux affaiblit la traçabilité, car l'artefact testé par l'équipe peut ne pas être l'artefact distribué aux utilisateurs.

L'écosystème API public actuel montre également pourquoi la maintenance est aussi importante que l'étendue. Tracker API présente un vaste catalogue d'API et de ressources pour les développeurs, tandis que les commentaires sur les récapitulatifs publics de API soulignent la charge de maintenance que cela représente lorsque les entrées couvrent la finance, le gouvernement, la santé, le machine learning, la météo et les transports. Un catalogue de canaux rencontre le même problème : des entrées obsolètes et un manque de propriété claire rendent une longue liste moins utile qu'une liste plus courte et maintenue.

Pour les détails d'implémentation concernant les tests contrôlés, consultez Capgo environnements de staging avec des canaux. Le modèle clé consiste à faire du mouvement de canal une action API explicite avec une étape d'approbation, plutôt que de permettre à n'importe quel job de build d'écrire directement en production.

Endpoints de monitoring et de diagnostic

Un déploiement n'est pas terminé quand l’API renvoie une réponse réussie. Il est terminé quand l'équipe peut expliquer quelle release les appareils ont découverte, téléchargée, installée et exécutée avec succès. Cela nécessite un workflow connectant les identifiants de release, l'appartenance aux canaux, les enregistrements des appareils, les logs et les données d'adoption.

Commencez par un enregistrement de corrélation dans votre système de déploiement. Stockez l'identifiant de l'app, l'identifiant de la release, le canal, la référence du commit, les métadonnées du build, l'horodatage de la requête et le statut API final. Lorsqu'un rapport de support arrive, l'opérateur doit pouvoir passer de l'appareil affecté à son canal et sa release sans chercher dans des logs CI non structurés.

Requêtez de manière précise avant d'agréger

Les endpoints de diagnostic supportent souvent des filtres par plage horaire, canal, appareil, plateforme ou release. Utilisez le filtre le plus précis pour répondre à votre question immédiate. Une requête large sur l'ensemble de votre base d'utilisateurs est plus lente, plus difficile à interpréter et risque de rencontrer des contraintes de pagination ou de quota.

Une séquence d'investigation pratique est la suivante :

• Vue release : Vérifiez si la release souhaitée existe et si elle a atteint le canal cible.
• Vue adoption : Comparez les appareils éligibles avec ceux ayant détecté ou installé la mise à jour.
• Vue échecs : Groupez les erreurs par release, plateforme, classe d'appareil et étape d'installation.
• Vue appareil : Inspectez les logs d'un appareil spécifique uniquement si les données agrégées indiquent un problème local.
• Vue incident : Conservez la réponse brute et les paramètres de requête utilisés pour l'investigation.

Ne supposez pas qu'un faible signal d'adoption signifie que le bundle est corrompu. Les appareils peuvent être hors ligne, exclus du canal, exécuter une version incompatible ou attendre la vérification de mise à jour de l'app. À l'inverse, un nombre élevé de téléchargements ne garantit pas un démarrage réussi. Séparez la découverte, le téléchargement, l'installation et la santé au runtime dès que API expose ces états.

Connectez les diagnostics à l'automatisation

Un worker planifié peut interroger le statut d'une release et déclencher une alerte lorsqu'une release reste dans un état non terminal plus longtemps que ne l'autorise le pipeline. Un autre worker peut collecter les enregistrements d'échec, normaliser les codes d'erreur et les joindre au ticket de déploiement. Gardez le payload de l'alerte concis, avec des liens vers la release, le canal et la requête de diagnostic filtrée.

L'authentification et la gestion des erreurs doivent appartenir à la même couche client que les appels d'endpoints. Le worker doit rafraîchir ou remplacer les identifiants selon la politique de credentials, classer les échecs d'autorisation séparément des requêtes malformées, et conserver 429 des réponses pour planifier des tentatives plutôt que de les traiter comme des erreurs serveur génériques.

Utilisez les curseurs de pagination ou les offsets documentés exactement comme spécifié. Un job de diagnostic par batch doit conserver sa position entre les pages et éviter de demander répétitivement la première page. Si les enregistrements peuvent changer pendant l'exécution d'une requête, utilisez une limite temporelle stable ou un filtre de release pour que le rapport final soit reproductible.

Limitation de débit et headers de sécurité

Les clients en production doivent inspecter les headers de réponse avant de choisir une stratégie de retry. Capturez X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After, ainsi que tout champ documenté RateLimit-* dans le middleware client API. Transmettez-les au contrôleur de retry et aux logs structurés. Ne vous code pas sur des quotas qui peuvent varier selon le compte, l'endpoint ou l'opération.

La distinction entre les informations de capacité et les instructions de retry détermine la requête suivante. Un header remaining-count indique la proximité du client par rapport à une limite. Retry-After spécifie quand le serveur autorise une nouvelle tentative. Respectez cette instruction lorsqu'elle est présente. Si la réponse ne fournit aucune indication temporelle, utilisez un exponential backoff avec jitter et une limite d'essais fixe.

Protégez la surface de gestion

Maintenez les requêtes de gestion Capgo sur un backend de confiance ou un runner CI. Une application Capacitor peut appeler un service restreint orienté application, mais elle ne doit jamais recevoir d'identifiants permettant de modifier les releases, les canaux ou les ressources de l'organisation. Imposez le TLS, validez les corps de requête et supprimez les headers d'autorisation des traces et des rapports d'erreur.

Appliquez des contrôles distincts par opération. Mettez en cache ou regroupez les requêtes de métadonnées en lecture seule lorsque c'est sûr. Attribuez des limites propres aux uploads, exports, tentatives de login et mutations de release. Regroupez les lectures de métadonnées indépendantes quand API supporte les opérations par batch, puis tenez compte des limites de requêtes et d'items du batch plutôt que de supposer qu'un batch coûte une seule unité. Les contrôles basés sur le comportement aident aussi à détecter les schémas d'abus distribués, comme décrit dans le Guide de sécurité sur le rate-limiting.

Utilisez des timeouts pour chaque requête et distinguez les échecs de transport des réponses HTTP. Un timeout laisse l'issue de la mutation inconnue : interrogez son statut avant de réessayer. Une 429 réponse constitue un retour explicite du serveur, et le client doit planifier la tentative suivante via ses headers.

Pour les déploiements Capacitor, Guide de Capgo sur le rate-limiting de API pour la conformité aux stores offrent une référence opérationnelle pertinente. Gardez vos credentials privés, respectez les headers du serveur et rendez les retries observables plutôt que silencieux.

Dépannage des erreurs API courantes

La plupart des échecs se répartissent en trois groupes : authentification, validation et throttling. Diagnostiquez le groupe avant de modifier code. Le statut de la réponse, le corps d'erreur structuré et les headers pertinents fournissent généralement assez d'informations pour choisir la prochaine action.

Échecs d'authentification

R 401 ou une réponse d'autorisation équivalente signifie généralement que le credential est manquant, malformé, expiré, révoqué ou envoyé avec le mauvais scheme. Vérifiez la variable d'environnement dans le job CI réel, pas seulement dans votre shell local. Confirmez que la requête inclut le format de header exact de la documentation API actuelle, puis testez le credential avec une opération en lecture seule.

Si la réponse indique une permission insuffisante plutôt qu'une identité invalide, traitez cela comme un problème d'autorisation. Demandez à un administrateur d'organisation de vérifier le scope de la clé, l'accès de l'app et l'environnement. Ne résolvez pas une erreur de permission en distribuant une clé personnelle aux privilèges trop larges.

Corps de requête invalides

Une réponse de validation signifie que le serveur a reçu la requête mais a rejeté sa structure ou ses valeurs. Comparez le payload au schéma actuel, en faisant attention aux champs obligatoires, aux types, aux valeurs enum, aux objets imbriqués et aux identifiants. Supprimez les champs non supportés plutôt que d'espérer que le service les ignore.

Loguez un payload masqué ainsi que les erreurs par champ de la réponse. Ajoutez une validation de schéma à votre CI pour que les métadonnées de release malformées échouent avant qu'un upload ne commence. Si l'opération est une mise à jour partielle, confirmez que l'endpoint attend bien un corps de type patch plutôt qu'un remplacement complet.

Throttling et mutations ambiguës

R 429 signifie que le worker doit cesser d'envoyer des requêtes et suivre les instructions de retry du serveur. Respectez Retry-After lorsqu'il est présent, appliquez du jitter lors du calcul d'un délai de repli, et empêchez plusieurs workers concurrents de retenter l'opération au même instant.

En cas de timeout lors d'un upload ou de la création d'une release, ne soumettez pas immédiatement une autre mutation. Recherchez ou récupérez l'opération en utilisant la référence de build générée par le client ou l'identifiant retourné si vous en avez reçu un. Si aucun identifiant n'est disponible, demandez au support documenté ou au mécanisme d'idempotence de API si la requête initiale a été complétée. Cela évite les releases en double et garantit la fiabilité de l'historique de déploiement final.

Capgo fournit une API REST publique pour gérer les ressources de livraison d'applications, les releases, les canaux, les appareils et les workflows de déploiement associés, afin que les équipes puissent connecter les opérations de live update à leurs systèmes CI/CD et de monitoring existants. Consultez la Capgo documentation actuelle, créez un identifiant de test à privilèges minimaux et validez un parcours complet de release et de rollback avant d'automatiser la promotion en production.