Individuelle API-Entwicklung: Ablauf und Kosten

Warum API-Design die Code-Implementierung überdauert

Sobald etwas Ihre API nutzt, ist deren Struktur praktisch eingefroren. Sie können alles dahinter neu schreiben; Sie können jedoch nicht einfach ein Feld umbenennen, von dem eine mobile App abhängt, denn alte App-Versionen bleiben jahrelang auf den Geräten der Nutzer.

Diese Asymmetrie ist der Grund, warum API-Arbeiten design-first erfolgen sollten. Eine Woche, die vor der Implementierung für die Abstimmung des Vertrags aufgewendet wird, spart später erheblich mehr, denn die Alternative ist, sich durch Versionierung aus Entscheidungen herauszuarbeiten, die an einem Nachmittag getroffen wurden.

Der funktionierende Prozess

1. Bestandsaufnahme der Nutzer

Wer ruft diese API auf, und was benötigen sie tatsächlich? Eine Web-Frontend, eine mobile App, eine Partnerintegration und ein internes Dashboard haben tatsächlich unterschiedliche Anforderungen. Mobile Clients legen Wert auf Payload-Größe und Roundtrips, was für einen Web-Client über Breitband nicht gilt.

2. Vertrag zuerst

Schreiben Sie die Spezifikation — OpenAPI für REST, ein Schema für GraphQL — und stimmen Sie diese vor der Implementierung ab. Das bringt zwei unmittelbare Vorteile: Frontend- und Backend-Arbeiten können parallel an einer Mock-Implementierung durchgeführt werden, und Meinungsverschiedenheiten werden in einer Dokumentenprüfung sichtbar, nicht erst beim Integrationstest.

3. Ressourcenmodellierung

Endpunkte sollten Ihr Geschäftsmodell widerspiegeln, nicht Ihre Datenbanktabellen. Das direkte Offenlegen der Tabellenstruktur ist zunächst praktisch, wird aber zum Käfig: Jede Schema-Änderung wird zu einer brechenden API-Änderung.

4. Authentifizierung und Autorisierung

Entscheiden Sie frühzeitig, denn nachträgliche Anpassungen sind schmerzhaft:

• API-Schlüssel für serverseitigen Zugriff durch Partner
• OAuth 2.0 / OIDC, wenn Nutzer Zugriff auf ihre eigenen Daten gewähren
• Kurzlebige JWTs mit Refresh-Tokens für eigene Apps

Halten Sie Autorisierung und Authentifizierung getrennt. Zu wissen, wer jemand ist, sagt nichts darüber aus, welche Datensätze er einsehen darf. Die Vermischung beider Aspekte ist eine häufige Ursache für Datenlecks.

5. Fehlerbehandlung, Paginierung, Versionierung

Die unspektakulären Teile, die bestimmen, wie angenehm es ist, mit der API zu arbeiten:

• Konsistente Fehlerstruktur mit einem maschinenlesbaren Code und einer menschlichen Nachricht
• Cursor-Paginierung statt Offset, damit Ergebnisse stabil bleiben, während sich die Daten ändern
• Versionierung ab Tag 1 — /v1/ kostet jetzt nichts und spart später eine Migration
• Ratenbegrenzung mit klaren Headern, damit Nutzer zurückstecken können, statt stumm abgeschnitten zu werden

6. Dokumentation als Liefergegenstand

Generierte Referenzdokumentation plus durchgearbeitete Beispiele, einschließlich Authentifizierung und Bedeutung häufiger Fehler. Wenn ein kompetenter Entwickler innerhalb von zwanzig Minuten nach dem Lesen keinen erfolgreichen Aufruf tätigen kann, ist die Dokumentation nicht abgeschlossen.

REST oder GraphQL

REST für die überwiegende Mehrheit der Projekte. HTTP-Caching funktioniert, die Fehlersuche ist einfach, jeder Entwickler kennt es bereits, und die Tool-Unterstützung ist universell.

GraphQL, wenn mehrere verschiedene Clients unterschiedliche Datenstrukturen benötigen oder wenn Over-Fetching bei mobilen Verbindungen messbare Kosten verursacht. Es bringt echte Komplexität mit sich — Caching, Begrenzung der Abfragekosten, Schutz vor tief verschachtelten Abfragen — die aktiv verwaltet werden muss.

GraphQL für einen einzelnen Web-Client zu wählen, ist normalerweise Komplexität ohne Gegenwert. REST zu wählen, wenn vier Clients jeweils eine andere Teilmenge abfragen, bedeutet entweder viele Endpunkte oder viel verschwendeten Payload.

Was es in Großbritannien tatsächlich kostet

Umfang	Typische Spanne
Fokussierte API, einige Ressourcen, Authentifizierung	£6.000 – £15.000
Integration mit einer dokumentierten Drittanbieter-API	£2.500 – £6.000
Integration mit veralteten oder undokumentierten Systemen	£10.000 – £30.000
API-Gateway, Ratenbegrenzung, Entwicklerportal	£8.000 – £20.000

Das Muster, das sich zeigt: Die Integrationskosten werden vom anderen System bestimmt, nicht von Ihnen. Eine moderne dokumentierte API ist in einer Woche umgesetzt. Ein veraltetes System ohne Dokumentation, inkonsistente Daten und keine Testumgebung kann einen Monat in Anspruch nehmen. Deshalb erfassen wir diese zunächst als zeitlich begrenzte Analysephase, statt blind einen Festpreis anzubieten — ein Festpreis auf ein unbekanntes System ist eine Vermutung, für die am Ende jemand bezahlt.

Integration veralteter Systeme

Die meisten echten Projekte sind keine Neuentwicklungen. Sie beinhalten etwas Altes, das dennoch das Geschäft am Laufen hält.

Wenn es eine API gibt, erwarten Sie Inkonsistenzen, langsame Antworten und undokumentierte Rate-Limits. Bauen Sie defensiv: Retries mit exponentiellem Backoff, Schaltkreissicherungen und eine Warteschlange, damit eine langsame Abhängigkeit Ihre Anwendung nicht mit in den Abgrund reißt.

Wenn es keine API gibt, sind die Optionen in absteigender Robustheit: ein geplanter Dateiaustausch (CSV oder XML über SFTP), eine schreibgeschützte Datenbankintegration, sofern der Anbieter dies zulässt, oder – in begrenzten Fällen – robotergestützte Prozessautomatisierung, die die Benutzeroberfläche steuert. Letzteres ist tatsächlich fragil und bricht zusammen, sobald der Anbieter ein Bildschirmelement ändert. Wir setzen es um, wenn es der einzige Weg ist, machen aber klar, was Sie damit akzeptieren.

Fügen Sie immer eine Anti-Korruptionsschicht hinzu. Übersetzen Sie das Modell des Altsystems an der Schnittstelle in Ihr eigenes, statt dessen Eigenheiten in Ihren Code zu tragen. Diese eine Entscheidung bestimmt, ob das spätere Ersetzen des Altsystems ein Projekt oder ein Albtraum wird.

Häufige Fehler

1. Datenbanktabellen als Endpunkte exponieren — koppelt Ihre API dauerhaft an Ihr Schema

2. Keine Versionierung — die erste brechende Änderung wird zur Notfallsituation

3. Authentifizierung nachträglich hinzufügen — führt fast immer zu einer Überarbeitung aller Endpunkte

4. Keine Rate-Limits — ein schlecht programmierter Client legt den Dienst für alle lahm

5. Inkonsistente Fehlerbehandlung — jeder Client schreibt maßgeschneiderte Fehlerbehandlung pro Endpunkt

6. Dokumentation als letzten Schritt — wird dann schlecht oder gar nicht erstellt

So sieht eine gute Lieferung aus

• OpenAPI-Spezifikation, die vor der Implementierung vereinbart wurde
• Automatisierte Tests, die den dokumentierten Vertrag abdecken
• Authentifizierung und Autorisierung als separate, getestete Komponenten
• Rate-Limits mit informativen Headern
• Strukturierte Protokollierung und Fehlerverfolgung
• Dokumentation mit durchgearbeiteten Beispielen
• Eine überwachte Staging-Umgebung, an der Clients entwickeln können

Nächste Schritte

Wenn Sie eine Integration planen und das System am anderen Ende unbekannt ist, ist der sinnvolle erste Schritt ein kurzer bezahlter Spitzenauftrag, um zu ermitteln, was tatsächlich möglich ist. Er kostet normalerweise nur einen Bruchteil des Projekts und zeigt gelegentlich, dass die Integration, für die Sie ein Angebot erhalten haben, nicht auf die beschriebene Weise umsetzbar ist.