API Versionierung 2026

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

Gesponsert

API Versionierung ermöglicht es, Schnittstellen weiterzuentwickeln, ohne bestehende Nutzer und Clients zu beeinträchtigen.

Kompakte Beschreibung

API Versionierung ist die gezielte Verwaltung von Änderungen an einer Schnittstelle über die Zeit. Sie betrifft REST APIs, GraphQL Schemas und gRPC Services gleichermaßen. Ziel ist es, neue Features und Korrekturen einzuführen, ohne bestehende Clients zu brechen. REST APIs nutzen häufig Versionierung im Pfad oder Header, GraphQL setzt auf Schema Evolution und Deprecation, während gRPC mit Protobuf und semantischer Versionierung arbeitet. Unabhängig vom Stil müssen Änderungen kategorisiert, kommuniziert und dokumentiert werden. Eine klare Versionierungsstrategie ist ein zentrales Element des API Lifecycle Managements und der langfristigen Stabilität einer Plattform.

Wichtige Komponenten

Kompatible und inkompatible Änderungen

Eine kompatible Änderung fügt neue Funktionen hinzu, ohne bestehende Clients zu stören. Beispiele sind optionale neue Felder, zusätzliche Endpunkte oder neue Filter. Eine inkompatible Änderung verändert bestehendes Verhalten, wie das Entfernen von Feldern, das Ändern von Pflichtfeldern oder das Umbenennen von Endpunkten. Inkompatible Änderungen erfordern eine neue Version oder zumindest eine sorgfältige Migration.

REST API Versionierung

Bei REST APIs sind URI Versioning und Header Versioning die gängigsten Strategien. URI Versioning nutzt Pfade wie /v1/products und ist besonders cachefreundlich. Header Versioning überträgt die Version über einen Header wie api-version: 1 oder Accept: application/vnd.shop.v2+json. Content Negotiation ist flexibel, aber aufwendiger.

GraphQL Schema Evolution

GraphQL verwendet kein klassisches Versioning im Pfad. Stattdessen wird das Schema schrittweise weiterentwickelt. Neue Felder und Typen können hinzugefügt werden, ohne bestehende Queries zu brechen. Veraltete Felder werden mit dem @deprecated Directive markiert. Clients entscheiden selbst, wann sie auf neue Felder umsteigen.

gRPC und Protobuf Versionierung

gRPC nutzt Protocol Buffers für die Nachrichtendefinition. Neue Felder können hinzugefügt werden, solange sie mit sorgfältigen Feldnummern versehen sind. Alte Clients ignorieren unbekannte Felder, neue Clients können mit Defaultwerten umgehen. Semantische Versionierung hilft, Major, Minor und Patch Releases zu kommunizieren.

Semantische Versionierung

Semantische Versionierung verwendet die Schreibweise Major.Minor.Patch. Major steht für inkompatible Änderungen, Minor für neue kompatible Features und Patch für Fehlerbehebungen. Für externe APIs wird oft nur die Major Version öffentlich kommuniziert, um die Komplexität für Nutzer gering zu halten.

Deprecation und Migration

Wenn eine Version oder ein Feld nicht mehr unterstützt werden soll, markierst Du es als deprecated. Für GraphQL nutzt Du @deprecated, für REST Header wie Deprecation oder Sunset. Du dokumentierst die Migration, informierst Nutzer früh und setzt ein klares End-of-Life Datum.

Versionierung in der Dokumentation

Dokumentation sollte für jede Version verfügbar sein, inklusive Changelog und Migrationsanleitung. Nutzer müssen erkennen, welche Änderungen eine neue Version bringt und welche Aktionen für den Umstieg erforderlich sind.

Caching und Versionierung

Versionierung im Pfad ist besonders einfach zu cachen, weil jede Version eine eigene URL hat. Bei Header Versioning oder GraphQL müssen Caches so konfiguriert werden, dass sie relevante Unterschiede berücksichtigen. Andernfalls kann es zu falschen Cache-Treffern kommen.

Monitoring und Nutzungsanalyse

Überwache, welche Versionen genutzt werden. So erkennst Du, wann alte Versionen sicher abgeschaltet werden können. Rate Limiting und Logging pro Version helfen, die Auslastung und Probleme zu erkennen.

API Governance

In größeren Organisationen regelt API Governance, wie Versionen verwaltet werden. Standards für Versionierung, Deprecation, Kommunikation und Dokumentation sorgen für Konsistenz über viele Teams und APIs hinweg.

Praxisbeispiel

Ein Unternehmen bietet eine REST API und eine GraphQL API an. Für die REST API wird eine inkompatible Änderung an den Adressdaten eingeführt.

REST API v1:

GET /v1/customers/42
{
  "id": 42,
  "name": "Musterfirma",
  "address": "Musterstraße 12, 10115 Berlin"
}

REST API v2:

GET /v2/customers/42
{
  "id": 42,
  "name": "Musterfirma",
  "address": {
    "street": "Musterstraße 12",
    "zip": "10115",
    "city": "Berlin",
    "country": "DE"
  }
}

GraphQL Schema Evolution:

type Customer {
  id: ID!
  name: String!
  address: String @deprecated(reason: "Use addressObject instead")
  addressObject: Address
}

type Address {
  street: String!
  zip: String!
  city: String!
  country: String!
}

Im GraphQL-Fall kann der Client schrittweise von address auf addressObject umsteigen, ohne die API-Version im Pfad zu ändern. Bei REST wechselt der Client von v1 auf v2.

IRC-Security.de

Cybersecurity Artikel und Tutorials

FAQ: API Versionierung

Weiter im API Lernpfad

Der nächste Artikel im API Lernpfad behandelt Idempotenz im API-Design: Webhooks und praktische Beispiele — warum idempotente Operationen für zuverlässige APIs unerlässlich sind.

Quellen

1. https://www.rfc-editor.org/rfc/rfc9110
2. https://graphql.org/learn/best-practices/
3. https://protobuf.dev/programming-guides/proto3/

Buchempfehlungen zur API-Entwicklung

Wenn Du Dich weiter mit API Versionierung, API Design und Softwarearchitektur beschäftigen möchtest, empfehlen wir Dir die folgenden Bücher:

API-Entwicklung

Bücher über API-Design, REST, GraphQL, OpenAPI und API-Architektur

REST und HTTP: Entwicklung und Integration nach REST-Prinzipien von Stefan Tilkov

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

API-Design: Praxishandbuch für Java- und Webservice-Entwickler

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

Microservices: Grundlagen flexibler Softwarearchitekturen von Eberhard Wolff

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

Premium VPS Hosting

Schnelle und sichere VPS Server

Gesponsert