Capgo öffentliche API Liste: Vollständige Entwicklerreferenz

Wahrscheinlich nutzt du gerade eine Deployment-Pipeline, die manuell funktioniert, aber instabil wird, sobald das Team wiederholbare Releases benötigt. Ein Developer erstellt ein Bundle, lädt es vom Laptop hoch, checkt ein Dashboard, verschiebt einen Channel und wartet dann auf die Adoption-Daten. Dieser Prozess mag bei kleinen Projekten ausreichen, erzeugt aber vermeidbare Risiken, wenn mehrere Apps, Umgebungen und Deployment-Jobs dieselbe Infrastruktur nutzen.

Eine hilfreiche öffentliche API Liste sollte mehr beantworten als nur „welche Endpoints gibt es?“. Sie sollte zeigen, wie Authentifizierung, Resource-IDs, Release-Status, Quotas, Header, Retries und Batch-Workflows zusammenspielen. Dieser Guide betrachtet die Capgo API aus dieser operativen Perspektive – mit Patterns, die für Capacitor Teams relevant sind, die CI/CD-Automatisierung statt isolierter Test-Requests bauen.

Inhaltsverzeichnis

• Die Capgo API Authentifizierung verstehen
  • Identität von Autorisierung trennen
• Deine API Credentials generieren
  • Key mit Zweck erstellen
  • Rotation ohne Ausfallzeiten
• Core-Endpoints für das App-Management
  • Identifier-first Workflow aufbauen
• Releases erstellen und verwalten
  • Release-Payload vorbereiten
  • Retries sicher gestalten
• Channel-Strategie und Rollout-Patterns
• Monitoring- und Diagnose-Endpoints
  • Vor der Aggregation gezielt abfragen
  • Diagnose mit Automatisierung verbinden
• Rate Limiting und Security Headers
  • Die Management-Oberfläche schützen
• Häufige API Fehler beheben
  • Authentifizierungsfehler
  • Ungültige Request-Bodies
  • Throttling und unklare Mutationen

Capgo API Authentifizierung verstehen

Der häufigste Fehler bei der ersten Integration ist das Senden eines validen Requests mit dem falschen Credential-Format. Ein aus dem Dashboard kopierter Key ist nicht automatisch ein Bearer-Token, und ein Bearer-Token ist nutzlos, wenn der Request den Authorization Header weglässt oder unter einem falschen Scheme sendet. Der Server gibt dann einen Authentifizierungsfehler zurück, noch bevor er den Endpoint, das Payload oder die App-ID prüft.

Identifizieren Sie zuerst, wie die aktuelle Capgo API Dokumentation das Credential nennt, und reproduzieren Sie den Beispiel-Request exakt. Bei einem typischen Bearer-Token-Request folgt der Authorization-Header diesem Muster:

Authorization: Bearer YOUR_TOKEN

Speichern Sie das Credential beim lokalen Testen in einer Umgebungsvariable. In der CI/CD sollten Sie es über den Secret Store der Plattform injizieren, anstatt es in ein Repository zu committen, in ein Mobile Bundle zu packen oder als Query-String zu nutzen. Eine Mobile App darf niemals Management-Credentials enthalten, da alles, was auf ein Gerät geliefert wird, letztlich inspiziert werden kann.

Identität von Autorisierung trennen

Authentifizierung klärt, wer die Anfrage stellt. Autorisierung bestimmt, was diese Identität ändern darf. Behandle beides als getrennte Prüfungen beim Design eines Deployment-Services.

Ein persönlicher Key ist für Tests praktisch, koppelt die Produktions-Automatisierung aber an ein einzelnes Konto. Ein Team-Key ist für eine gemeinsame Pipeline besser geeignet, sofern die Organisation ihn ohne Unterbrechung anderer Jobs widerrufen kann. Nutze getrennte Credentials für Dev-, Staging- und Production-Workflows, wenn das Dashboard und das Berechtigungsmodell dies unterstützen.

Bevor du einen Release-Endpoint aufrufst, teste eine risikoarme Read-Operation. Bestätige, dass:

• Der Host korrekt ist: Verwende die für die aktive Umgebung dokumentierte API Base URL.
• Der Header vollständig ist: Füge das erforderliche Authorization-Schema und einen Accept Header für JSON-Responses hinzu.
• Der Body korrekt encodiert ist: Sende diesen Content-Type: application/json nur, wenn die Anfrage JSON enthält.
• Der Scope ausreicht: Ein Credential, das App-Metadaten lesen darf, ist möglicherweise nicht berechtigt, ein Release zu erstellen oder zu verteilen.
• Die Antwort wird sicher protokolliert: Statuscodes und Request-IDs werden erfasst, aber Keys, Tokens, Bundle-Inhalte und sensible Gerätedaten werden geschwärzt.

Öffentliche API Kataloge haben sich von einfachen Verzeichnissen zu operativen Discovery-Tools entwickelt. Das historische Konto von ProgrammableWeb beschreibt ein Verzeichnis, das im Januar 2018 über 19.000 APIs umfasste,nachdem 2.294 neue APIs im Jahr 2017 hinzugefügt wurden und durchschnittlich mehr als 2.000 Ergänzungen pro Jahr seit Januar 2014 erfolgten. Diese Historie erklärt, warum eine moderne öffentliche API Liste Ingenieuren helfen muss, das Integrationsverhalten zu bewerten, statt nur eine URL zu finden.

Für verwandte Überlegungen zur clientseitigen Zugriffskontrolle siehe Capgo App-Autorisierungsmuster. Dasselbe Prinzip gilt auch hier: Bewahre Management-Credentials auf vertrauenswürdigen Servern auf, definiere Berechtigungen bewusst und sorge dafür, dass fehlgeschlagene Autorisierungen leicht zu diagnostizieren sind.

Erstellen Ihrer API Credentials

Die Erstellung von Credentials sollte als Änderung des Access-Managements betrachtet werden, nicht als einfacher Setup-Schritt. Die genauen Dashboard-Labels können sich ändern; nutze daher die aktuelle Capgo Oberfläche und Dokumentation als Referenz, auch wenn der Workflow konsistent bleibt.

Erstelle einen Key mit einem Zweck

Öffne die Organisations- oder Kontoeinstellungen, navigiere zum API oder Developer-Credentials-Bereich und wähle die Option zum Erstellen eines Keys. Gib dem Key einen Namen, der seine Aufgabe beschreibt, wie etwa eine Staging-Deployment-Pipeline oder ein Production-Release-Worker. Vermeide Namen, die nur auf einer Person basieren, da die Zuständigkeit bei Teamwechseln unklar wird.

Wähle die am engsten gefassten Berechtigungen für diesen Workflow aus. Ein Job, der nur den Deployment-Status liest, sollte keine Berechtigung zum Löschen von Apps oder Ändern von Channels erhalten. Wenn die Oberfläche Scopes auf Organisations- und App-Ebene anbietet, wähle die kleinere Grenze, die den Job noch unterstützt.

Kopiere das Secret, sobald das Dashboard es anzeigt. Viele Credential-Systeme zeigen den vollständigen Wert nur während der Erstellung an. Speichere es in deinem CI/CD Secret Manager und teste den Abruf innerhalb der Pipeline, ohne den Wert selbst auszugeben. Ein lokaler .env Dateien können bei der Entwicklung helfen, müssen aber von der Versionskontrolle ausgeschlossen und dürfen niemals in ein Capacitor Web-Verzeichnis gebündelt werden.

Rotation ohne Ausfallzeiten

Halten Sie bei der Rotation von Credentials einen Überlappungszeitraum ein. Fügen Sie den Ersatz zum Secret Store hinzu, deployen Sie die Pipeline-Konfiguration, die ihn nutzt, führen Sie einen harmlosen authentifizierten Read aus und entziehen Sie erst dann den alten Key. Wenn der Service mehrere aktive Keys unterstützt, halten Sie den alten Wert verfügbar, bis jeder Worker und Scheduled Job umgestellt wurde.

Dokumentieren Sie für das Team Key-Owner, Zweck, Umgebung, Erstellungsdatum und Revocation-Verfahren in einem internen Zugangsregister. Speichern Sie das Secret selbst nicht in diesem Register. Das macht die Incident Response praktikabel, ohne die Dokumentation in ein weiteres Secret-Repository zu verwandeln.

Die UK-Regierungsstandards für API empfehlen, frühzeitig ein OpenAPI-Dokument zu entwerfen, Inputs zu validieren, unbekannte Attribute abzulehnen, TLS 1.2 oder höher zu nutzen und OAuth 2.0 für die Zugriffskontrolle einzusetzen. Diese Prinzipien sind auch nützlich, wenn die Integration API Keys nutzt: Definieren Sie den Contract vor dem Bau der Automatisierung, lehnen Sie unerwartete Inputs ab und behandeln Sie Transport Security als essenziell.

Für Pipeline-Storage und Rotation-Patterns nutzen Sie: Capgo Leitfaden zum Management von Secrets in CI/CD-Pipelines.

Core Endpoints für das App-Management

App-Management ist die Control Plane für alles Weitere. Release-Erstellung, Channel-Zuweisung, Bundle-Distribution und Diagnostik benötigen alle eine stabile App-ID. Ein häufiger Fehler ist es, einen menschenlesbaren App-Namen durch jeden Job zu schleifen und zu hoffen, dass er eindeutig bleibt. Löse die App einmal auf, speichere die kanonische ID und nutze diese ID für alle folgenden Operationen.

Eine Produktions-Integration sollte den App-Lifecycle um vier Kernfunktionen herum aufbauen:

Erfinde keine Endpoint-Pfade aus einem Blogpost oder einem alten SDK. Lies die aktuelle maschinenlesbare Definition und generiere daraus einen typisierten Client oder Request-Wrapper. Die OpenAPI-Spezifikation beschreibt ein sprachunabhängiges Format für HTTP APIs, mit dem Menschen und Tools Endpoints, Authentifizierung, Request-Schemas, Responses und das Verhalten entdecken können, ohne den Quell-code oder den Netzwerkverkehr zu prüfen.

Identifier-first Workflow aufbauen

Ein Deployment-Worker sollte erst einen Read durchführen, bevor er eine Mutation ausführt:

1. Die Organisation und den App-Kontext auflösen.
2. Den App-Datensatz abrufen und prüfen, ob er zum erwarteten Account gehört.
3. Die Zielplattform und Umgebung mit der zurückgegebenen Konfiguration vergleichen.
4. Den kanonischen App-Identifier im Job-State speichern.
5. Das Release oder die Konfigurationsänderung mit diesem Identifier absenden.
6. Speichere die Response-ID für späteres Polling und Diagnosen.

Diese Sequenz verhindert eine extrem teure Fehlerklasse, bei der ein gültiger Key die falsche App aktualisiert, weil eine Pipeline-Variable auf ein altes Projekt zeigt. Füge vor dem Schreibvorgang eine explizite Environment-Assertion hinzu, z. B. indem du verlangst, dass ein Staging-Job auf die Staging-App abzielt.

Nutze Response-Schemas statt losem JSON-Zugriff. Wenn API ein App-Objekt mit Identifier, Name, Status und Konfigurationsfeldern zurückgibt, validiere nur die Felder, die dein Job benötigt, und erlaube andere Ergänzungen. Das Ablehnen unbekannter Request-Attribute schützt dich vor falsch geschriebenen Konfigurations-Keys, während ein tolerantes Response-Parsing dem Client hilft, Response-Erweiterungen ohne Absturz zu überstehen.

Trenne bei Rollback-Designs die App-Identität von der Release-Identität. Die Dokumentation zu Versionierung und Rollbacks von Capgo ist die maßgebliche Referenz für den Betrieb. Ein Rollback sollte einen bekannten, stabilen Release- oder Channel-Zustand auswählen, anstatt eine App-Konfiguration aus dem Gedächtnis neu zu erstellen.

Releases erstellen und verwalten

Ein Production-Release kann fehlschlagen, obwohl der Upload erfolgreich war. Das Artefakt wurde eventuell korrekt gespeichert, aber die Verarbeitung ist noch nicht abgeschlossen, das Channel-Assignment ist nicht erfolgt oder berechtigte Geräte haben das Update noch nicht erhalten. Betrachte den Workflow als Sequenz beobachtbarer Zustandsänderungen, mit einer dauerhaften ID und einem Retry-Plan für jede Operation.

Release-Payload vorbereiten

Verwende das aktuelle Capgo Schema für Property-Namen, Request-Pfade und Pflichtfelder. Ein Request-Body, der von einem ähnlich benannten Endpoint kopiert wurde, kann teilweise akzeptiert oder aus unerwarteten Gründen abgelehnt werden. Praktisch gesehen enthält der Payload drei Bereiche:

• Anwendungsidentität: Die App-ID, die von der entsprechenden Control-Plane-Operation zurückgegeben wird.
• Release-Metadaten: Die Version, Bundle-ID, der Build-Kontext und die Kompatibilitätsinfos, die von API erwartet werden.
• Distribution-Absicht: Der Channel oder Rollout-Kontext, sofern die Release-Operation dies unterstützt.

Validiere das Bundle vor dem Senden. Prüfe, ob der Capacitor Build die erwarteten Web-Assets enthält, ob die Version mit den CI-Metadaten übereinstimmt und ob der Job nicht gerade eine unvollständig geschriebene Datei liest. Berechne einen lokalen Checksum, falls API einen akzeptiert. Speichere die Build-URL, die Commit-Referenz und die vom Server vergebene Release-ID im Deployment-Record, damit spätere Jobs Upload, Processing und Distribution korrelieren können.

Eine zuverlässige Sequenz ist:

1. Baue die App in einem Clean Workspace.
2. Führe Unit-, Integration- und plattformspezifische Checks aus.
3. Erstelle oder lade das Bundle über die dokumentierte Release-Operation hoch.
4. Polle die zurückgegebene Operation oder Release-Ressource, bis sie einen Endzustand erreicht.
5. Verknüpfe das abgeschlossene Release mit dem vorgesehenen Channel.
6. Prüfe Adoptions- und Fehler-Signale vor der Promotion.

Eine Upload-Antwort bestätigt die Annahme durch den Service, nicht die Auslieferung an die Nutzer. Verarbeitungsstatus, Geräte-Eignung, Konnektivität und Channel-Mitgliedschaft entscheiden weiterhin darüber, ob ein Update ein Gerät erreicht.

Retries sicher machen

Ein Timeout verrät nicht, ob der Server die Anfrage abgelehnt oder vor dem Verbindungsabbruch abgeschlossen hat. Ein erneutes Senden desselben Releases kann daher Duplikate oder widersprüchliche Versionen erzeugen. Nutze einen Idempotency-Key, wenn Capgo das unterstützt. Ohne diese Möglichkeit frage vor einem Retry einer Mutation die Release-Metadaten oder eine clientseitig generierte Build-ID ab.

Batch-Uploads brauchen Status pro Item. Schreibe jede App-Variante in eine persistente Queue und halte das Ergebnis separat fest. Ein Worker-Retry sollte nur unfertige Items auswählen, statt nach einem Fehler den gesamten Batch erneut zu senden. Falls ein Bulk-Endpoint verfügbar ist, prüfe, ob die Antwort ein Ergebnis für jedes Item enthält. Ein aggregierter Success-Status kann eine fehlgeschlagene Variante verbergen, während ein aggregierter Error bereits abgeschlossene Arbeit verschleiert.

Operative Regel: Speichere die Release-ID des Servers sofort und nutze sie für Prüfungen der Verarbeitung, Channel-Zuweisung und Diagnose.

Rate Limits betreffen sowohl Uploads als auch Polling. API-Leitfaden zu Rate Limits beachten, dass Quotas die jeweilige Aktion widerspiegeln sollten und Clients brauchbare Header sowie Retry-Verhalten benötigen. Behandeln Sie Release-Erstellung, Status-Polling, Suchen und sensible Mutationen separat. Ein Polling-Loop, der mit Upload-Geschwindigkeit retried, kann die Quota für Korrekturmaßnahmen aufbrauchen.

Lesen Sie Rate-Limit-Header bei Rückgabe aus, respektieren Sie das vom Server vorgegebene Retry-Intervall und nutzen Sie zunehmende Delays, falls diese fehlen. Fügen Sie Jitter hinzu, damit nicht mehrere CI-Worker gleichzeitig retrien. Begrenzen Sie das Polling, stoppen Sie bei einem Terminal State und schreiben Sie den finalen Response Body in die CI-Logs (nach Entfernung von Credentials und Tokens). Falls ein Deployment abgebrochen wird, protokollieren Sie den Akteur oder den Automation-Job, den aktuellen Release-Status und ob das Artifact für einen späteren Retry verfügbar bleibt.

Channel-Strategie und Rollout-Patterns

Das Channel-Design ist eine Entscheidung zur Release-Governance, nicht nur eine reine Benennungsfrage. Staging-, Beta- und Production-Channels bedienen unterschiedliche Zielgruppen und sollten verschiedene Promotion-Regeln haben. Die richtige Wahl hängt davon ab, wie viel Unsicherheit im Bundle besteht und wie schnell das Team Feedback benötigt.

Ein Staging-Channel sollte deterministisch sein. Weise bekannte Testgeräte oder Accounts zu, schütze den Channel vor versehentlichen Änderungen und nutze CI, um Releases erst nach erfolgreichen Checks zu promoten. Beta ist sinnvoll, wenn produktionsnaher Traffic wichtig ist, erfordert aber eine klare Zielgruppendefinition und einen Support-Prozess für Fehlermeldungen. Production sollte langweilig sein: Das Release hat alle vorherigen Gates bestanden, das Rollback-Ziel ist bekannt und das Monitoring ist bereits aktiv.

Der API Workflow sollte diese Grenzen widerspiegeln. Eine Pipeline kann das Release einmal erstellen, es Staging zuweisen und dasselbe Release-Objekt nach der Validierung promoten. Ein Rebuild zwischen den Channels schwächt die Traceability, da das vom Team getestete Artefakt nicht unbedingt das Artefakt ist, das an die Nutzer verteilt wird.

Das aktuelle öffentliche API Ökosystem zeigt auch, warum Wartung genauso wichtig ist wie die Breite des Angebots. API Tracker bietet einen riesigen Katalog an APIs und Developer-Ressourcen, wobei Kommentare zu öffentlichen API Roundups die Wartungslast verdeutlichen, die entsteht, wenn Einträge Bereiche wie Finanzen, Behörden, Gesundheit, Machine Learning, Wetter und Transport abdecken. Ein Channel-Katalog hat dasselbe Problem: Veraltete Einträge und unklare Zuständigkeiten machen eine große Liste weniger nützlich als eine kleinere, gepflegte.

Für Details zur Implementierung von kontrolliertem Testing siehe Capgo Staging-Umgebungen mit Channels. Das entscheidende Muster besteht darin, Channel-Wechsel als explizite API Aktion mit einer Approval-Grenze zu definieren, anstatt jedem Build-Job zu erlauben, direkt in die Production zu schreiben.

Monitoring- und Diagnose-Endpoints

Ein Deployment ist nicht abgeschlossen, wenn API eine erfolgreiche Antwort liefert. Es ist erst dann abgeschlossen, wenn das Team erklären kann, welches Release die Geräte entdeckt, heruntergeladen, installiert und erfolgreich ausgeführt haben. Das erfordert einen Workflow, der Release-IDs, Channel-Zugehörigkeit, Gerätedaten, Logs und Adoption-Daten verknüpft.

Beginnen Sie mit einem Correlation-Record in Ihrem Deployment-System. Speichern Sie die App-ID, Release-ID, den Channel, die Commit-Referenz, Build-Metadaten, den Request-Zeitstempel und den finalen API Status. Wenn ein Support-Ticket eingeht, sollte der Operator direkt vom betroffenen Gerät zu dessen Channel und Release navigieren können, ohne in unstrukturierten CI-Logs suchen zu müssen.

Vor dem Aggregieren gezielt abfragen

Diagnose-Endpoints unterstützen oft Filter nach Zeitraum, Channel, Gerät, Plattform oder Release. Nutze den engsten Filter, der die konkrete Frage beantwortet. Eine breite Abfrage über die gesamte Installationsbasis ist langsamer, schwerer zu interpretieren und stößt eher an Pagination- oder Quota-Limits.

Eine praktische Vorgehensweise ist:

• Release-Ansicht: Prüfe, ob das gewünschte Release existiert und den Ziel-Channel erreicht hat.
• Adoptions-Ansicht: Vergleiche berechtigte Geräte mit denen, die das Update entdeckt oder installiert haben.
• Fehler-Ansicht: Gruppiere Fehler nach Release, Plattform, Gerätetyp und Installationsphase.
• Geräte-Ansicht: Untersuche Logs für ein bestimmtes Gerät erst, wenn das aggregierte Muster auf ein lokales Problem hindeutet.
• Incident-Ansicht: Speichere die Raw-Response und die für die Untersuchung verwendeten Query-Parameter.

Gehe nicht davon aus, dass eine geringe Adoption bedeutet, dass das Bundle defekt ist. Geräte können offline sein, vom Channel ausgeschlossen sein, eine inkompatible Version nutzen oder auf den Update-Check der App warten. Umgekehrt beweist eine hohe Download-Zahl keinen erfolgreichen Start. Trenne Discovery, Download, Installation und Runtime-Health, sobald API diese Zustände offenlegt.

Diagnose mit Automatisierung verknüpfen

Ein Scheduled Worker kann den Release-Status abfragen und einen Alert auslösen, wenn ein Release länger als im Pipeline-Limit erlaubt in einem nicht-terminalen Zustand verweilt. Ein weiterer Worker kann Fehlerprotokolle sammeln, Error-Codes normalisieren und an das Deployment-Ticket anhängen. Halte den Alert-Payload kurz, inklusive Links zum Release, Channel und der gefilterten Diagnose-Abfrage.

Authentifizierung und Error Handling gehören in dieselbe Client-Layer wie die Endpoint-Aufrufe. Der Worker sollte Credentials gemäß der Policy erneuern oder ersetzen, Autorisierungsfehler separat von malformed Requests klassifizieren und 429 Responses für das Retry-Scheduling erhalten, anstatt sie als generische Server-Fehler zu behandeln.

Nutze Pagination-Cursor oder dokumentierte Offsets exakt wie vorgegeben. Ein Batch-Diagnose-Job muss seine Position zwischen den Seiten beibehalten und vermeiden, wiederholt die erste Seite abzufragen. Falls sich Datensätze während einer Abfrage ändern können, nutze eine stabile Zeitgrenze oder einen Release-Filter, damit der Bericht reproduzierbar bleibt.

Rate Limiting und Security Header

Production-Clients sollten Response-Header prüfen, bevor sie einen Retry-Pfad wählen. Erfasse X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After, sowie alle dokumentierten RateLimit-* Felder in der API Client-Middleware. Übergib diese an den Retry-Controller und die Structured Logs. Hardcode keine code Quotas, da diese je nach Account, Endpoint oder Operation variieren können.

Die Unterscheidung zwischen Kapazitätsinformationen und Retry-Anweisungen bestimmt die nächste Anfrage. Ein 'remaining-count' Header zeigt an, wie nah der Client am Limit ist. Retry-After gibt an, wann der Server einen weiteren Versuch erlaubt. Beachte diese Anweisung, falls sie vorhanden ist. Falls die Response keine Zeitvorgabe macht, nutze Bounded Exponential Backoff mit Jitter und einem festen Limit für die Anzahl der Versuche.

Schütze die Management-Oberfläche

Capgo Management-Requests sollten auf einem vertrauenswürdigen Backend oder CI-Runner laufen. Eine Capacitor App darf zwar einen eingeschränkten, clientseitigen Service aufrufen, sollte aber niemals Credentials erhalten, mit denen Releases, Channels oder Organisations-Ressourcen geändert werden können. Erzwinge TLS, validiere die Bodies und entferne Authorization-Header aus Traces und Error-Reports.

Wende separate Limits pro Operation an. Cache oder bündle Read-only-Metadaten-Requests, wo sicher möglich. Weise Uploads, Exports, Login-Versuche und Release-Mutationen eigene Limits zu. Batch unabhängige Metadaten-Reads, wenn API Batch-Operationen unterstützt, und berücksichtige dabei die Limits für Requests und Items pro Batch, anstatt davon auszugehen, dass ein Batch nur eine Einheit kostet. Verhaltensbasierte Controls helfen zudem, verteilte Abuse-Muster zu erkennen, wie im ... Sicherheitshinweise zum Rate-Limiting.

Nutze Timeouts für jeden Request und unterscheide Transportfehler von HTTP-Responses. Ein Timeout lässt das Ergebnis der Mutation offen; prüfe daher den Status, bevor du einen Retry startest. Eine 429 Response ist explizites Server-Feedback, und der Client sollte den nächsten Versuch anhand der Header planen.

Für Capacitor Deployments, Capgo’s API Rate-Limiting-Guide für App-Store-Compliance bietet eine hilfreiche Referenz für den Betrieb. Halte Credentials privat, beachte Server-Header und mache Retries beobachtbar statt sie stillschweigend auszuführen.

Fehlerbehebung bei häufigen API Fehlern

Die meisten Fehler lassen sich in drei Gruppen unterteilen: Authentifizierung, Validierung und Throttling. Diagnostiziere die Gruppe, bevor du code änderst. Der Response-Status, der strukturierte Error-Body und die relevanten Header liefern meist genug Infos für den nächsten Schritt.

Authentifizierungsfehler

Ein 401 oder eine entsprechende Autorisierungs-Response bedeutet meist, dass das Credential fehlt, fehlerhaft ist, abgelaufen, widerrufen wurde oder mit dem falschen Scheme gesendet wurde. Prüfe die Umgebungsvariable im eigentlichen CI-Job, nicht nur in der lokalen Shell. Stelle sicher, dass der Request das exakte Header-Format der aktuellen API Dokumentation nutzt, und teste das Credential dann mit einer Read-only-Operation.

Deutet die Response auf unzureichende Berechtigungen statt einer ungültigen Identität hin, behandle es als Autorisierungsproblem. Bitte einen Admin, den Scope, den App-Zugriff und die Umgebung des Keys zu prüfen. Löse Berechtigungsfehler nicht, indem du einen breit privilegierten persönlichen Key verteilst.

Ungültige Request-Bodies

Eine Validierungsantwort bedeutet, dass der Server die Anfrage erhalten, aber die Struktur oder die Werte abgelehnt hat. Vergleiche das Payload mit dem aktuellen Schema und achte dabei auf Pflichtfelder, Typen, Enum-Werte, verschachtelte Objekte und Identifier. Entferne nicht unterstützte Felder, anstatt darauf zu hoffen, dass der Service sie einfach ignoriert.

Logge ein anonymisiertes Payload sowie die Fehler auf Feldebene der Response. Integriere Schema-Validierungen in deine CI, damit fehlerhafte Release-Metadaten fehlschlagen, bevor ein Upload startet. Falls es sich um ein Partial Update handelt, stelle sicher, dass der Endpoint einen Patch-Style-Body erwartet und keinen vollständigen Ersatz.

Throttling und mehrdeutige Mutationen

Ein 429 bedeutet, dass der Worker die Anfragen stoppen und die Retry-Anweisungen des Servers befolgen muss. Beachte Retry-After bei vorhandener Angabe Jitter bei der Berechnung der Fallback-Verzögerung, um zu verhindern, dass mehrere Worker gleichzeitig einen Retry ausführen.

Bei einem Timeout während des Uploads oder der Release-Erstellung darf keine weitere Mutation sofort gesendet werden. Suche oder rufe die Operation über die clientseitig generierte Build-Referenz oder die zurückgegebene ID auf. Falls keine ID verfügbar ist, prüfe über den dokumentierten Support oder den Idempotenz-Mechanismus von API, ob die ursprüngliche Anfrage erfolgreich war. Das verhindert doppelte Releases und sorgt für verlässliche Deployment-Logs.

Capgo bietet eine öffentliche REST API zur Verwaltung von App-Delivery-Ressourcen, Releases, Channels, Geräten und Deployment-Workflows, damit Teams Live-Update-Prozesse mit ihren bestehenden CI/CD- und Monitoring-Systemen verknüpfen können. Schau dir die aktuelle Capgo Dokumentation an, erstelle ein Test-Credential mit minimalen Berechtigungen und validiere einen vollständigen Release- und Rollback-Pfad, bevor du die Production-Promotions automatisierst.