API & Integration Entwicklung

API-First: Warum Ihre API das wichtigste Produkt ist

Ihre API ist nicht nur ein technisches Detail. Sie ist die Schnittstelle zwischen Ihrem Geschäftsmodell und der Welt. Zwischen Ihrem Frontend und Ihrem Backend. Zwischen Ihrer App und Ihren Partnern. Zwischen Ihrem System und dem Payment-Provider.

Eine schlecht designte API kostet Sie Monate an Entwicklungszeit, frustrierte Entwickler und verlorene Integrationspartner. Eine gut designte API beschleunigt die Entwicklung, ermöglicht neue Geschäftsmodelle und skaliert mit Ihrem Unternehmen.

Was API-First bedeutet

API-First ist nicht "wir bauen erst die API". Es bedeutet:

1. API als Vertrag: Das API-Schema wird vor der Implementierung definiert. Frontend- und Backend-Teams arbeiten parallel gegen diesen Vertrag
2. API als Produkt: Die API wird mit derselben Sorgfalt designed wie die UI. Konsistente Namensgebung, klare Fehlermeldungen, umfassende Dokumentation
3. API als Plattform: Jede Funktion die existiert, ist über die API erreichbar. Kein "das geht nur über die UI"

Wie API-First unsere Entwicklungsgeschwindigkeit verdoppelt hat: Development as a Subscription

REST API Entwicklung

REST ist der Standard für Web-APIs. Einfach, verständlich, universell. Wir bauen REST APIs nach OpenAPI 3.1 Spezifikation mit NestJS und TypeScript.

Unsere REST API Standards

Konsistente Ressourcen-Struktur:

• GET /api/v1/users — Liste mit Pagination, Filtering, Sorting
• GET /api/v1/users/:id — Einzelne Ressource
• POST /api/v1/users — Erstellen
• PATCH /api/v1/users/:id — Teilweise aktualisieren
• DELETE /api/v1/users/:id — Löschen

Response-Format:

• Konsistente Envelope mit data, meta, errors
• HTTP-Statuscodes korrekt verwendet (201 für Create, 204 für Delete)
• Pagination mit cursor oder offset je nach Use Case
• HATEOAS-Links für API-Navigation

OpenAPI/Swagger Dokumentation

Jede API die wir bauen kommt mit vollständiger OpenAPI 3.1 Dokumentation:

• Auto-generiert aus NestJS Decorators und TypeScript-Typen
• Interaktive Docs: Swagger UI zum Testen direkt im Browser
• Client-Generierung: Automatische SDK-Generierung für JavaScript, Swift, Kotlin, Python
• Versionierung: Changelog und Breaking Change Dokumentation
• Beispiele: Realistische Request/Response Beispiele für jeden Endpoint

API-Versionierung

Wir nutzen URL-basierte Versionierung (/api/v1/, /api/v2/). Warum:

• Explizit: Jeder sieht welche Version er nutzt
• Parallel betreibbar: v1 und v2 laufen gleichzeitig während Clients migrieren
• Einfaches Routing: Load Balancer können Versionen auf verschiedene Services routen
• Sunset Policy: v1 wird 6 Monate nach v2-Release deprecated, 12 Monate nach v2 abgeschaltet

GraphQL API Entwicklung

Für komplexe Datenmodelle und SaaS-Produkte empfehlen wir GraphQL. Der Client bestimmt exakt welche Daten er braucht, nicht der Server.

Wann REST, wann GraphQL?

Kriterium	REST	GraphQL
Einfache CRUD-APIs	Ideal	Overkill
Komplexe Datenmodelle	Viele Endpoints, Over-Fetching	Ein Endpoint, flexible Queries
Mobile Clients mit begrenzter Bandbreite	Problematisch	Ideal, nur benötigte Felder
Öffentliche APIs	Standard, jeder kennt es	Höhere Lernkurve
Echtzeit-Features	WebSocket separat	Subscriptions eingebaut
Datei-Upload	Einfach	Erfordert Multipart-Spec
Caching	HTTP-Caching nativ	Erfordert Apollo/urql Cache
API-Evolution	Neue Version nötig	Schema-Evolution ohne Versioning

Unser GraphQL Stack

• Code-First: Schema wird aus TypeScript-Klassen generiert, nicht manuell geschrieben
• NestJS GraphQL Module: Tiefe Integration mit Dependency Injection
• DataLoader: N+1 Query Prevention automatisch
• Subscriptions: Real-time Updates über WebSocket
• Complexity Analysis: Schutz vor teuren Queries
• Persisted Queries: Performance-Optimierung für Produktions-Clients

Authentifizierung und Autorisierung

Auth ist der kritischste Teil jeder API. Ein Fehler hier und sensible Daten sind exponiert. Wir implementieren Auth nach bewährten Standards, nie selbst erfunden.

Authentication Strategien

Strategie	Wann sinnvoll
JWT mit Refresh Token	Standard für SPAs und Mobile Apps
OAuth2 + OIDC	Social Login, Enterprise SSO
API Keys	Server-to-Server Kommunikation
Session-based	Klassische Web-Apps mit SSR
Passkeys/WebAuthn	Passwortlose Authentifizierung
mTLS	High-Security Machine-to-Machine

Authorization Patterns

• RBAC (Role-Based Access Control): Nutzer haben Rollen, Rollen haben Permissions
• ABAC (Attribute-Based Access Control): Zugriff basiert auf Attributen (Abteilung, Standort, etc.)
• Resource-Based: Nutzer dürfen nur eigene Ressourcen bearbeiten
• Field-Level: Bestimmte Felder sind nur für bestimmte Rollen sichtbar (GraphQL)

Security Best Practices

• Token Rotation: Refresh Tokens werden nach einmaliger Nutzung invalidiert
• Rate Limiting: Pro User, pro IP, pro Endpoint
• CORS: Whitelist statt Wildcard
• Input Validation: Jeder Input wird mit Zod validiert bevor er die Business-Logik erreicht
• SQL Injection: Unmöglich durch Prisma ORM
• CSRF Protection: Double-Submit Cookie Pattern
• Security Headers: Helmet.js mit strikter CSP

Payment Integration mit Stripe

Stripe ist unser Standard für Payment. Wir haben über 30 Stripe-Integrationen implementiert, von einfachen Einmalzahlungen bis zu komplexen Subscription-Modellen mit Usage-Based Billing.

Was wir mit Stripe umsetzen

• Checkout Sessions: Gehostete Zahlungsseite, PCI-konform ohne eigene Zertifizierung
• Subscriptions: Recurring Billing mit Trials, Proration, Upgrades/Downgrades
• Usage-Based Billing: Metered Billing basierend auf API-Calls, Storage, etc.
• Connect: Marketplace-Payments mit Split und Payout an Händler
• Invoicing: Automatische Rechnungserstellung und -versand
• Tax: Automatische Steuerberechnung (inkl. EU-VAT, USt-ID Validierung)

Webhook-Handling für Stripe

Stripe kommuniziert asynchron über Webhooks. Unser robustes Webhook-Handling:

1. Signature Verification: Jeder Webhook wird kryptographisch verifiziert
2. Idempotency: Doppelt empfangene Events werden ignoriert
3. Retry Logic: Fehlgeschlagene Verarbeitung wird mit Exponential Backoff wiederholt
4. Event Queue: Webhooks werden sofort acknowledged und asynchron verarbeitet
5. Dead Letter Queue: Dauerhaft fehlgeschlagene Events werden zur manuellen Prüfung gespeichert
6. Monitoring: Alerts bei fehlgeschlagenen Webhooks oder unerwarteten Events

Drittanbieter-Integrationen

Fast jedes Projekt erfordert Integrationen mit externen Services. Wir haben Erfahrung mit dutzenden APIs und kennen die typischen Fallstricke.

Häufige Integrationen

Service	Use Case	Komplexität
Stripe	Payments, Subscriptions	Mittel
SendGrid / Postmark	Transaktionale E-Mails	Niedrig
Twilio	SMS, WhatsApp, Voice	Mittel
AWS S3	File Storage	Niedrig
Google Maps	Geocoding, Routing	Niedrig
Shopify	E-Commerce, Inventory	Hoch
Salesforce	CRM-Synchronisation	Hoch
HubSpot	Marketing Automation	Mittel
Slack	Notifications, Bot	Niedrig
Google Analytics / PostHog	Event Tracking	Niedrig

Integration Best Practices

• Abstraktionsschicht: Jede externe API wird hinter einem Interface abstrahiert. Provider wechseln ohne Business-Logik zu ändern
• Circuit Breaker: Wenn eine externe API down ist, bricht unser System nicht zusammen
• Retry mit Backoff: Temporäre Fehler werden automatisch wiederholt
• Timeout-Konfiguration: Jede externe API hat ein explizites Timeout
• Fallback-Strategie: Was passiert wenn die Integration nicht verfügbar ist?
• Monitoring: Response-Times und Error-Rates jeder Integration werden überwacht

Webhook-Handling: Der unterschätzte Komplex

Webhooks sind die Achillesferse vieler Systeme. Ein verlorener Webhook von Stripe bedeutet eine nicht verbuchte Zahlung. Ein doppelt verarbeiteter Webhook bedeutet eine doppelte Bestellung.

Unser Webhook-Framework

Jedes Webhook-Handling das wir implementieren folgt diesem Pattern:

1. Empfang: Webhook wird empfangen, Signatur geprüft, sofort mit 200 acknowledged
2. Persistierung: Event wird in die Datenbank geschrieben bevor es verarbeitet wird
3. Deduplizierung: Event-ID wird geprüft, Duplikate werden ignoriert
4. Verarbeitung: Event wird asynchron aus der Queue verarbeitet
5. Retry: Bei Fehlern wird automatisch mit Exponential Backoff wiederholt
6. Dead Letter: Nach X fehlgeschlagenen Versuchen wird das Event zur manuellen Prüfung markiert
7. Monitoring: Dashboard mit allen empfangenen Events, Status und Fehler-Details

Webhook-Sicherheit

• Signatur-Verifikation: HMAC-SHA256 oder RSA, je nach Provider
• IP-Whitelist: Nur bekannte IPs dürfen Webhooks senden
• Replay-Protection: Zeitstempel-Validierung gegen Replay-Attacks
• Payload-Validierung: Webhook-Body wird gegen ein Schema validiert

Rate Limiting und API Protection

Eine öffentliche API ohne Rate Limiting ist ein offenes Scheunentor. Wir implementieren mehrstufiges Rate Limiting:

Rate Limiting Strategien

Ebene	Limit	Zweck
Global	10.000 req/min	DDoS-Schutz
Per IP	100 req/min	Bot-Schutz
Per User	1.000 req/min	Fair Use
Per Endpoint	Individuell	Schutz teurer Operationen
Per Plan	Basierend auf Subscription	Monetarisierung

Implementierung

• Token Bucket oder Sliding Window Algorithmus in Redis
• 429 Response mit Retry-After Header
• Rate Limit Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• Graceful Degradation: Überschreitungen werden geloggt, nicht geblockt (bei internen APIs)

API Monitoring und Observability

Eine API die Sie nicht überwachen, ist eine API die irgendwann stillschweigend versagt. Wir implementieren umfassendes Monitoring:

• Health Checks: /health Endpoint der Datenbank, Redis, externe Services prüft
• Response Time Tracking: P50, P95, P99 Latenz pro Endpoint
• Error Rate Monitoring: Alerts bei Anstieg der 4xx/5xx Responses
• Request Logging: Strukturierte Logs mit Correlation IDs für Request-Tracing
• Dependency Monitoring: Response-Times und Availability aller externen Services
• Dashboard: Grafana-Dashboard mit den wichtigsten Metriken

Mehr zu Monitoring und Infrastruktur: Cloud & DevOps

So arbeiten wir an Ihrer API

1. API Design Workshop

Gemeinsam definieren wir Ressourcen, Endpunkte, Datenmodelle und Authentifizierungs-Strategie. Das Ergebnis ist eine OpenAPI-Spec oder ein GraphQL-Schema das als Vertrag dient.

2. Implementation

NestJS mit TypeScript. Jeder Endpoint mit Input-Validierung, Error-Handling und Tests. API-Dokumentation wird automatisch generiert.

3. Integration Testing

Jede Integration wird mit Mocks und echten Sandbox-Accounts getestet. Stripe Test-Mode, SendGrid Sandbox, etc.

4. Security Review

Penetration-Tests auf die API. OWASP Top 10, Auth-Bypass-Versuche, Input-Fuzzing.

5. Go-Live

Deployment mit CI/CD Pipeline, Monitoring-Setup, Runbook für On-Call.

Häufige Fragen zur API Entwicklung

REST oder GraphQL für mein Projekt?

Siehe unsere Entscheidungsmatrix oben. Kurzfassung: REST für öffentliche APIs und einfache CRUD. GraphQL für SaaS-Produkte mit React Frontend und komplexen Datenmodellen. Wir beraten Sie kostenlos.

Wie dokumentiere ich meine API am besten?

OpenAPI/Swagger für REST, das Schema selbst für GraphQL. Wir generieren beides automatisch aus dem Code, kein manuelles Pflegen von Docs. Zusätzlich: Postman Collection für einfaches Testing durch Ihre Partner.

Wie sichere ich meine API ab?

Auth (JWT/OAuth2), Rate Limiting, Input Validation, CORS, Security Headers, Dependency Audits. Wir implementieren alle Schichten. Keine Abkürzungen bei Security.

Was kostet API Entwicklung?

Ab €2.495/Monat als Subscription. Für API-intensive Projekte mit Drittanbieter-Integrationen empfehlen wir Scale 150 oder Advanced 300. Vergleich: Freelancer vs Agentur vs Subscription.

Können Sie meine bestehende API modernisieren?

Ja. Wir migrieren von Express zu NestJS, von JavaScript zu TypeScript, von unstrukturierten Endpoints zu OpenAPI-konformen APIs. Schrittweise, mit Feature-Parity-Tests. Parallel dazu reduzieren wir Technical Debt.

Brauche ich eine API wenn ich nur eine Web-App habe?

Ja. Auch wenn Sie heute nur ein React Frontend haben, wird irgendwann eine Mobile App, ein Partner-Portal oder eine Automatisierung dazukommen. Eine saubere API von Anfang an macht das trivial.

Verwandte Leistungen

• Node.js Backend: Die Server-Logik hinter Ihrer API
• TypeScript: End-to-End Typsicherheit für Ihre API
• Cloud & DevOps: Deployment, Monitoring und Skalierung
• React Entwicklung: Das Frontend das Ihre API konsumiert
• Mobile Entwicklung: Native iOS und Android Apps als API-Consumer