API Plattform für Design-First API Workflow

TL;DR

Design-First bedeutet: Die API-Spezifikation wird vor dem Implementierungscode geschrieben und steuert danach Mocks, Dokumentation, Tests und Client-/Server-Stubs. Dadurch wird die Spezifikation zur Single Source of Truth. Dieser Artikel zeigt, wie ein Design-First-Workflow praktisch aussieht, welche Tool-Funktionen wichtig sind und wie Apidog diesen Workflow als Design-First-Plattform unterstützt.

Testen Sie Apidog noch heute

Apidog

Testen Sie Apidog kostenlos

Einleitung

Viele Entwickler starten APIs Code-First: Route schreiben, Annotationen ergänzen, Generator ausführen, Dokumentation erzeugen. Das funktioniert — bis Code und Dokumentation auseinanderlaufen.

Typische Probleme:

• Die Dokumentation beschreibt alte Response-Formate.
• Annotationen werden beim Refactoring vergessen.
• Frontend-Teams müssen warten, bis Backend-Endpunkte existieren.
• Breaking Changes werden erst bei der Integration sichtbar.

Design-First dreht den Ablauf um: Erst wird der API-Vertrag definiert, dann wird implementiert. Die OpenAPI-Spezifikation beschreibt Pfade, Methoden, Parameter, Request-Bodies, Responses, Authentifizierung, Feldbeschreibungen und Beispiele.

Aus dieser Spezifikation entstehen anschließend:

• Mock-Server
• API-Dokumentation
• Contract-Tests
• Client- oder Server-Stubs
• Review-Grundlage für Frontend, Backend und Produktteam

Der entscheidende Punkt: Design-First funktioniert nur, wenn das Tooling schnell genug ist. Wenn das Schreiben der Spezifikation mehr Reibung erzeugt als das direkte Implementieren, wird das Team den Prozess umgehen.

---

Was Design-First in der Praxis bedeutet

Design-First ist kein einzelnes Tool, sondern ein Workflow.

1. Vor dem Code: API-Vertrag definieren

Die API wird zuerst als OpenAPI-Spezifikation beschrieben.

Beispiel:

openapi: 3.0.3
info:
  title: "User API"
  version: 1.0.0

paths:
  /users/{id}:
    get:
      summary: Benutzerprofil abrufen
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Benutzerprofil"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfile"
        "404":
          description: "Benutzer nicht gefunden"

components:
  schemas:
    UserProfile:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          example: usr_123
        email:
          type: string
          format: email
          example: [e-mail]
        displayName:
          type: string
          example: Erika Mustermann

In dieser Phase werden die wichtigsten API-Entscheidungen getroffen:

• Benennung von Ressourcen
• Request- und Response-Strukturen
• Fehlerformate
• Statuscodes
• Authentifizierungsmodell
• Wiederverwendbare Schemas

2. Während der Entwicklung: Mock statt Blocker

Sobald die Spezifikation steht, wird ein Mock-Server daraus erzeugt.

Frontend kann sofort gegen den Mock entwickeln:

const response = await fetch("https://mock.example.com/users/usr_123");
const user = await response.json();

console.log(user.email);

Backend implementiert parallel gegen dieselbe Spezifikation. Beide Seiten arbeiten auf denselben Vertrag hin.

3. Nach der Implementierung: Contract validieren

Wenn der echte Endpunkt verfügbar ist, wird geprüft, ob seine Responses zur Spezifikation passen.

Beispielhafter Testfall:

import { expect } from "chai";

describe("GET /users/:id", () => {
  it("returns a valid user profile", async () => {
    const res = await fetch("https://api.example.com/users/usr_123");
    const body = await res.json();

    expect(res.status).to.equal(200);
    expect(body).to.have.property("id");
    expect(body).to.have.property("email");
  });
});

In einem vollständigen Design-First-Setup sollte diese Prüfung nicht nur manuell über Assertions laufen, sondern gegen das definierte OpenAPI-Schema validieren.

4. Bei Änderungen: Erst Spezifikation, dann Code

Wenn sich Anforderungen ändern, wird zuerst die Spezifikation angepasst. Danach prüfen Frontend, Backend und andere Stakeholder die Änderung.

Erst nach Freigabe wird implementiert.

Das verhindert stille Contract-Änderungen wie:

{
-  "name": "Erika"
+  "displayName": "Erika"
}

Solche Änderungen sind potenziell breaking und sollten sichtbar überprüft werden.

---

Was eine Design-First-Plattform leisten muss

Nicht jedes API-Tool eignet sich für Design-First. Entscheidend sind diese Funktionen.

Visueller API-Editor

Rohes YAML ist präzise, aber als primäre Designoberfläche oft zu langsam. Ein guter visueller Editor sollte:

• gültiges OpenAPI erzeugen
• Pfade, Methoden, Parameter und Responses strukturiert bearbeiten
• Schema-Komponenten wiederverwenden
• $ref unterstützen
• Validierungsfehler direkt anzeigen
• optional eine YAML-/JSON-Rohansicht bieten

OpenAPI-Validierung

Die Spezifikation muss gültig sein, bevor sie für Mocks, Dokumentation oder Codegenerierung verwendet wird.

Validierung sollte früh passieren, nicht erst in der CI-Pipeline.

Typische Fehler:

responses:
  200:
    description: OK

Korrekt wäre:

responses:
  "200":
    description: OK

Automatische Mock-Generierung

Ein Design-First-Tool sollte aus der Spezifikation direkt einen Mock-Endpunkt erzeugen.

Wichtig ist, dass der Mock nicht nur leere Objekte zurückgibt, sondern Schema-Informationen nutzt:

• format: email → gültige E-Mail-Adresse
• minimum / maximum → Werte im definierten Bereich
• enum → erlaubter Enum-Wert
• Arrays → passende Elementstruktur
• $ref → korrekt aufgelöste Komponenten

Dokumentationsvorschau

Die Spezifikation sollte sofort als lesbare API-Dokumentation sichtbar sein.

Damit können Produktmanager, Frontend-Leads oder QA früh Feedback geben, bevor Backend-Code existiert.

Review-Workflow

API-Änderungen sollten wie Code-Änderungen behandelt werden:

1. Änderung vorschlagen
2. Kommentare sammeln
3. Diskussion auf Endpunkt- oder Feldebene führen
4. Änderung freigeben
5. Implementierung starten

Export in Standard-OpenAPI

Die Spezifikation darf nicht im Tool eingeschlossen sein. Ein Export als OpenAPI 3.x ist wichtig, damit sie mit anderen Tools genutzt werden kann:

• Codegeneratoren
• API-Gateways
• Test-Frameworks
• Dokumentationsgeneratoren
• Linter

Beispiel mit openapi-generator:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated/client

---

Apidog als Design-First-Plattform

Apidog ist um die API-Spezifikation als zentrales Artefakt aufgebaut. Design, Mocking, Tests und Dokumentation beziehen sich auf dieselbe API-Definition.

Visueller OpenAPI-Editor

In Apidog werden Endpunkte formularbasiert beschrieben:

• Pfad
• HTTP-Methode
• Query-, Path- und Header-Parameter
• Request-Body
• Response-Schemas
• Beispiele
• Beschreibungen
• Validierungsregeln

Sie müssen kein YAML schreiben, können aber bei Bedarf in eine Rohansicht wechseln und die OpenAPI-/JSON-Darstellung direkt bearbeiten.

Praktischer Ablauf:

1. Neues Projekt erstellen
2. In den Design-Tab wechseln
3. Endpunkt anlegen, z. B. GET /users/{id}
4. Path-Parameter id definieren
5. Response 200 mit Schema UserProfile ergänzen
6. Fehlerantworten wie 404 oder 401 hinzufügen
7. Speichern und Mock verwenden

Wiederverwendbare Schema-Komponenten

Gemeinsame Objekte sollten als Komponenten modelliert werden.

Beispiele:

• UserProfile
• ErrorResponse
• PaginationMeta
• Address
• AuthToken

So vermeiden Sie doppelte Definitionen.

Beispiel:

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: USER_NOT_FOUND
        message:
          type: string
          example: Der Benutzer wurde nicht gefunden.

Danach kann jeder Endpunkt darauf referenzieren:

responses:
  "404":
    description: Nicht gefunden
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ErrorResponse"

Echtzeit-Dokumentationsvorschau

Während Sie Endpunkte entwerfen, kann die Dokumentation aus derselben Spezifikation angezeigt werden.

Das ist besonders hilfreich für Reviews:

• Sind Feldnamen verständlich?
• Sind Fehlerfälle dokumentiert?
• Sind Statuscodes konsistent?
• Gibt es Beispiele für Request und Response?
• Ist die Authentifizierung klar beschrieben?

Wenn etwas in der Dokumentation unklar ist, ist meist auch die API unklar.

Smart Mock: Von der Spezifikation zum nutzbaren Mock

Wenn ein Endpunkt im Designer gespeichert wird, kann der Mock-Server genutzt werden. Der Mock basiert auf den definierten Schemas.

Beispiele:

• string mit format: email erzeugt E-Mail-ähnliche Werte
• integer mit minimum und maximum erzeugt Werte im Bereich
• enum nutzt erlaubte Werte
• verschachtelte Objekte folgen der Schemastruktur
• referenzierte Komponenten werden aufgelöst

Damit kann das Frontend früh arbeiten, ohne auf Backend-Implementierung zu warten.

Beispielhafter Frontend-Flow:

type UserProfile = {
  id: string;
  email: string;
  displayName?: string;
};

async function loadUser(id: string): Promise<UserProfile> {
  const res = await fetch(`${MOCK_BASE_URL}/users/${id}`);

  if (!res.ok) {
    throw new Error(`Request failed: ${res.status}`);
  }

  return res.json();
}

Team-Review und Änderungshistorie

API-Spezifikationsänderungen sollten sichtbar sein. In Apidog können Workspace-Mitglieder Änderungen prüfen und Kommentare zu Endpunkten oder Feldern hinterlassen.

Für Design-First ist das wichtig, weil die Spezifikation nicht nur Dokumentation ist, sondern der Vertrag zwischen Teams.

---

Design-First vs. Code-First: Die tatsächlichen Kompromisse

Design-First ist nicht in jedem Kontext automatisch besser. Die Wahl hängt von Teamgröße, API-Stabilität und Koordinationsaufwand ab.

Vorteile von Design-First

• Frontend und Backend können parallel arbeiten
• Dokumentation basiert auf der Quelle der Wahrheit
• Integrationsprobleme werden früher sichtbar
• API-Verträge sind explizit und überprüfbar
• Breaking Changes fallen schneller auf
• Reviews finden vor der Implementierung statt

Nachteile von Design-First

• Vorabzeit für Spezifikationsarbeit
• Lernkurve für OpenAPI und Tooling
• Disziplin erforderlich, damit Code und Spezifikation synchron bleiben
• Zu frühes Überspezifizieren kann unnötig einschränken

Vorteile von Code-First

• Schneller Start bei kleinen oder experimentellen Projekten
• Weniger Prozess für Solo-Entwickler
• Kein separates Spezifikations-Tool nötig

Nachteile von Code-First

• Dokumentation ist sekundär und kann abweichen
• Frontend wartet häufig auf Backend
• API-Verträge sind oft implizit
• Breaking Changes sind schwerer zu erkennen
• Refactoring erfordert manuelle Dokumentationspflege

Für Teams mit mehreren Entwicklern und enger Frontend-Backend-Abstimmung ist Design-First meist robuster. Der größte Nutzen entsteht bei Features, bei denen Integration und Abstimmung teuer sind.

---

Tools, die Design-First-Workflows unterstützen

Apidog

Apidog kombiniert visuellen Editor, Mocking, Dokumentation, Tests und Team-Review in einem Tool. Der Fokus liegt darauf, die Spezifikation als zentrale Quelle zu verwenden und daraus die weiteren Artefakte abzuleiten.

Stoplight Studio

Stoplight Studio ist ein starker OpenAPI-Editor mit Spectral-Linting für API-Governance. Es eignet sich besonders für Organisationen, die Stilregeln und Governance-Prozesse stark gewichten.

SwaggerHub

SwaggerHub ist eine etablierte Plattform für OpenAPI-Bearbeitung und Zusammenarbeit. Sie ist in vielen Enterprise-Umgebungen verbreitet und passt gut zu Teams, die bereits im Swagger-Ökosystem arbeiten.

Postman mit API Builder

Postman bietet API-Design-Funktionen und kann OpenAPI-Spezifikationen nutzen. Für Teams, die bereits stark mit Collections arbeiten, kann das praktikabel sein. Design- und Collection-Workflows fühlen sich jedoch häufig getrennt an.

Insomnia mit Dokumentenmodus

Insomnia unterstützt OpenAPI-Bearbeitung und grundlegendes Mocking. Es ist eine leichtere Option für Solo-Entwickler oder kleinere Setups.

---

Einen Design-First-Workflow in Apidog einrichten

Schritt 1: Mit der Spezifikation beginnen

Starten Sie nicht im Request-Builder, sondern im Design-Bereich.

Definieren Sie zuerst:

• Endpunktpfad
• HTTP-Methode
• Authentifizierung
• Request-Parameter
• Request-Body
• Response-Schemas
• Fehlerfälle

Beispiel-Mindestumfang für einen Endpunkt:

paths:
  /orders:
    post:
      summary: Bestellung erstellen
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateOrderRequest"
      responses:
        "201":
          description: Bestellung erstellt
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Order"
        "400":
          description: Ungültige Anfrage

Schritt 2: Gemeinsame Komponenten zuerst definieren

Bevor viele Endpunkte entstehen, sollten wiederverwendbare Schemas angelegt werden.

Typische Basiskomponenten:

components:
  schemas:
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
        pageSize:
          type: integer
          minimum: 1
        total:
          type: integer
          minimum: 0

    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string

Das verhindert, dass jedes Team eigene Varianten von Fehler- oder Pagination-Formaten baut.

Schritt 3: Mock-URL früh teilen

Sobald der Endpunkt gespeichert ist, kann der Mock genutzt werden.

Empfohlener Ablauf:

1. Endpunkt speichern
2. Mock-URL kopieren
3. Frontend-Team informieren
4. Beispiel-Request und Beispiel-Response teilen
5. Offene Fragen direkt an der Spezifikation klären

Frontend kann dann sofort gegen den Mock integrieren.

Schritt 4: Dokumentation vor dem Code prüfen

Öffnen Sie die generierte Dokumentationsansicht und prüfen Sie:

• Gibt es für jeden Parameter eine Beschreibung?
• Sind Pflichtfelder klar markiert?
• Sind Fehlerfälle dokumentiert?
• Sind Beispiele realistisch?
• Sind Statuscodes konsistent?
• Ist das Response-Schema vollständig?

Wenn die Dokumentation unklar ist, wird die Implementierung später ebenfalls Interpretationsspielraum lassen.

Schritt 5: Spezifikation für den Sprint stabilisieren

Nach Review und Freigabe sollte die Spezifikation für die aktuelle Implementierung stabil bleiben.

Wenn während der Implementierung eine Änderung nötig wird:

1. Spezifikation aktualisieren
2. Änderung reviewen
3. Frontend/Backend abstimmen
4. Mock und Dokumentation aktualisieren
5. Implementierung anpassen

Keine stillen Änderungen direkt im Code.

Schritt 6: Schema-Validierung in CI einbauen

Contract-Tests sollten verhindern, dass Implementierung und Spezifikation auseinanderlaufen.

Ein mögliches CI-Prinzip:

# 1. Backend starten
npm run start:test

# 2. API-Tests ausführen
npm run test:api

# 3. OpenAPI-Schema-Validierung prüfen
npm run test:contract

Wichtig ist nicht der konkrete Befehl, sondern die Regel:

Jede Response, die nicht zur Spezifikation passt, muss den Build fehlschlagen lassen.

---

FAQ

Ist Design-First nur für REST-APIs?

Nein. Das Prinzip gilt für alle Schnittstellen, bei denen ein Vertrag definiert werden kann:

• REST mit OpenAPI
• GraphQL mit Schema-First-Ansatz
• gRPC mit Protobuf
• Event-getriebene Systeme mit AsyncAPI

Apidog unterstützt REST- und GraphQL-Design. Für gRPC erfüllen Proto-Dateien denselben Contract-First-Zweck.

Müssen wir jeden Endpunkt definieren, bevor wir entwickeln?

Nein. Design-First kann auch featureweise eingeführt werden.

Praktischer Ansatz:

1. Neues Feature auswählen
2. Nur die dafür nötigen Endpunkte spezifizieren
3. Mock bereitstellen
4. Frontend und Backend parallel entwickeln
5. Contract-Tests ergänzen

So kann ein bestehendes Code-First-Projekt schrittweise Design-First übernehmen.

Wie passt Design-First in agile Sprints?

Design-First wird Teil der Sprintplanung.

Typischer Ablauf:

1. Feature-Anforderung klären
2. API-Vertrag entwerfen
3. Spezifikation reviewen
4. Mock freigeben
5. Frontend und Backend parallel implementieren
6. Contract-Tests ausführen

Die Spezifikationsprüfung ersetzt keine Sprintplanung, sondern macht API-Abhängigkeiten früher sichtbar.

Was, wenn die Implementierung von der Spezifikation abweichen muss?

Dann sollte zuerst die Spezifikation geändert werden.

Richtiger Ablauf:

1. Abweichung identifizieren
2. Spezifikation aktualisieren
3. Stakeholder informieren
4. Änderung reviewen
5. Implementierung anpassen
6. Tests aktualisieren

So bleibt die Spezifikation die Quelle der Wahrheit.

Können Server-Stubs aus Apidogs OpenAPI-Export generiert werden?

Ja. Exportieren Sie die Spezifikation als OpenAPI 3.x und verwenden Sie einen Standard-Codegenerator.

Beispiel:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./generated/server

Oder für einen TypeScript-Client:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated/client

Wie handhaben wir Spezifikationsversionierung?

Für kleinere Änderungen reicht eine Änderungshistorie im Projekt. Für größere Versionssprünge sind getrennte Versionen sinnvoll, z. B.:

• /v1/users
• /v2/users

Oder separate Projekte bzw. Branches, wenn beide Versionen parallel gepflegt werden müssen.

---

Design-First erfordert etwas Vorarbeit, reduziert aber Integrationskosten und Abstimmungsaufwand. Der wichtigste Erfolgsfaktor ist gutes Tooling: Wenn Spezifikation, Mock, Dokumentation und Tests aus derselben Quelle entstehen, wird Design-First nicht zum Zusatzprozess, sondern zum normalen API-Workflow.