{"canonical_url":"https://engineer.company/de/glossary/api/","content_markdown":"# API\n\n## Was es ist\n\nEine API, kurz für Application Programming Interface, ist die veröffentlichte Menge von Operationen, die Software anderer Software anbietet: wie jede Operation heißt, was sie annimmt, was sie zurückgibt und wie sie Probleme meldet. Der Plural lautet APIs. Der Aufrufer kennt diese Oberfläche und nichts dahinter. Das Programm auf der anderen Seite kann deshalb neu geschrieben, auf einen anderen Rechner verschoben oder in drei Teile zerlegt werden. Solange die Oberfläche bestehen bleibt, funktioniert der Aufrufer weiter.\n\nDer Begriff umfasst mehrere Ebenen. Die API einer Bibliothek besteht aus exportierten Funktionen und Typen, die innerhalb eines Prozesses aufgerufen werden. Die API eines Betriebssystems ist seine Menge von Systemaufrufen. POSIX standardisiert einen gemeinsamen Kern, damit ein Programm mit `open` und `read` auf mehreren Unix-artigen Kerneln gebaut werden kann. Eine Web-API wird über ein Netzwerk angeboten, fast immer über HTTP. Das ist heute meist gemeint: ein Server, der Anfragen an Adressen wie `/v1/orders` beantwortet, üblicherweise mit JSON im Nachrichtentext.\n\nWeb-APIs haben mehrere Formen. Ressourcenorientierte, häufig REST-artig genannt, geben jedem Gegenstand eine Adresse und verwenden HTTP-Methoden zum Lesen und Ändern. RPC-artige APIs wie gRPC veröffentlichen benannte Prozeduren mit vorab deklarierten Argumenten und Ergebnissen. GraphQL bietet einen Endpunkt und ein Typsystem. Der Client schreibt eine Abfrage, die genau die gewünschten Felder benennt. Webhooks kehren die Richtung um: Bei einem Ereignis ruft der Anbieter eine vom Kunden registrierte Adresse auf.\n\nDrei benachbarte Begriffe werden verwechselt. Ein Protokoll wie HTTP bestimmt den Transport der Nachrichten; eine API legt fest, was ein bestimmter Dienst darin sagt. Ein SDK ist eine Bibliothek in einer Programmiersprache, die eine API umhüllt, sodass Entwickler eine Funktion aufrufen, statt Anfragen zusammenzubauen. Die Implementierung ist schließlich der Code hinter der API, den der Aufrufer nie lesen muss.\n\n## Warum es wichtig ist\n\nEine API ist der Teil eines Systems, auf dem andere aufbauen. Damit ist sie eine Zusage, die ihren Code überdauert. Einen Handler umzuschreiben dauert einen Nachmittag. Seine Rückgabe zu ändern kann eine bereits auf Kundentelefonen installierte App, den nächtlichen Import eines Partners oder ein vergessenes Skript beschädigen.\n\nDie erste Entscheidung betrifft deshalb die Nutzer. Eine private API nur für das eigene Frontend kann im selben Pull Request wie ihr einziger Client geändert werden. Eine öffentliche API verändert sich durch Abkündigung und Vorankündigung. Jedes ausgelieferte Feld bleibt zu unterstützen, solange jemand es liest.\n\nDie zweite Entscheidung ist die Strenge des Vertrags. Eine strenge API deklariert für jede Eingabe Typ und Grenze, weist Unbekanntes zurück und beantwortet jeden Fehler mit einem genauen Statuscode. Sie fängt Fehler am Eingang ab und lässt sich leichter dokumentieren, testen und zur Clientgenerierung nutzen. Eine tolerante API nimmt alles an und versucht das Beste. Das wirkt im ersten Monat freundlich und macht später jede zufällige Eigenheit der Implementierung zu einem Verhalten, auf das jemand baut. Strenge kostet am Anfang Entwurfszeit; Toleranz kostet später mehr, zu einem Zeitpunkt, den niemand auswählt.\n\nDie dritte Entscheidung betrifft fremde APIs. Ein Zahlungsanbieter, Kartendienst oder Sprachmodell wird vom Produkt aufgerufen, aber nicht kontrolliert. Preise ändern sich, Versionen werden eingestellt, Kontingente enger. Direkte Aufrufe eines Anbieters an fünfzig Stellen machen den Wechsel zur Neuentwicklung. Ein Aufruf aus einem eigenen Modul beschränkt ihn auf dieses Modul. Der Wrapper kostet etwas Indirektion und schafft einen Ausweg.\n\nSemantic Versioning liefert das Vokabular für diese Zusage: Bei einer inkompatiblen Änderung der öffentlichen API steigt die Hauptversionsnummer. Ein Client kann deshalb allein an der Version erkennen, ob ein Upgrade verträglich ist. Über HTTP lässt sich ein Bruch an mehreren Stellen signalisieren. RFC 9205, die IETF-Empfehlung für HTTP-basierte Protokolle, nennt unter anderem eine neue Linkrelation, einen neuen Medientyp oder ein neues Headerfeld.\n\n## Wie es in der Praxis aussieht\n\nDie APIs mehrerer Projekte auf dieser Website wurden von einer Frage geprägt: Was gehört in die API und was anderswohin?\n\nNextMariner ist eine maritime Plattform für berufliche Vernetzung, Bewertungen von Unternehmen und geförderte Weiterbildung. Zum Architekturbeitrag der Gründerin gehörte es, [die Go-API bewusst schlank zu halten](/de/portfolio/a-maritime-platform-built-in-clean-layers/). Mit Huma auf Fiber übernimmt sie Routing, Eingabevalidierung, Sicherheitsfilterung und Ablaufsteuerung, enthält aber keinerlei Geschäftslogik. Die Regeln liegen in PostgreSQL-Funktionen, sodass eine Regeländerung in einer einzigen Schicht in SQL geschieht. Die Grenzen wurden aufgeschrieben und in Reviews durchgesetzt. Damit ist die API ein langweiliger Adapter, im guten Sinn.\n\nEin verwandtes Projekt nahm auch die Formung der Antworten aus der API. [PostgreSQL-Funktionen setzen jede Antwort als JSON zusammen](/de/portfolio/designed-a-json-passthrough-from-postgres-to-api/). Der Go-Handler erhält sie als `json.RawMessage` und leitet sie unverändert über einen kleinen `QueryJSON`-Helfer weiter. DTOs, Mapper und Antwortstrukturen, die eine geschichtete API sonst ansammelt, entfielen. Handler wurden erheblich kürzer, und das Frontend hing nicht länger von Go ab. Der Tausch verdient eine klare Benennung: Die Form der API-Antworten steht nun in SQL. Dort liest ein Reviewer den Vertrag.\n\nEine öffentlich erreichbare API muss sich auch verteidigen. Vor einem öffentlichen Verzeichnis von Firmen und Fachleuten stehen [22 jeweils auf ihren Pfad zugeschnittene Ratenbegrenzer](/de/portfolio/built-fail-closed-rate-limiting-and-anti-abuse/). Ihr Zustand liegt in Redis, damit Grenzen über Instanzen hinweg gelten. Ist Redis unerreichbar, verweigern sie den Verkehr. Cloudflare Turnstile, eine Ursprungssperre, eine eigene Challenge am Verzeichnis und 351 Zeilen Idempotenz-Middleware gegen doppelt ankommende Schreibwiederholungen vervollständigen den Schutz. Die Seite benennt den Preis offen: Ein Redis-Problem wird für Nutzer sichtbar. Das wurde einem Redis-Problem vorgezogen, das zum Abrechnungsproblem wird.\n\n## Wo es schiefgeht\n\nAPI-Fehler kommen meist spät, wenn Clients und Daten gewachsen sind.\n\n**Ein umbenanntes Feld bricht einen unbekannten Client.** Nach der Veröffentlichung hängt jemand an jedem beobachtbaren Detail: Feldnamen, Listenreihenfolge und Fehlertext. Aus `customer_name` wird `name`, und bei der nächsten Anfrage bricht die Partnerintegration. Ändern Sie stattdessen durch Ergänzung: Fügen Sie das neue Feld neben dem alten hinzu, markieren Sie das alte als abgekündigt und beobachten Sie die Protokolle, bis es niemand mehr liest. Entfernen Sie es erst in einer neuen Hauptversion.\n\n**Ein Listenendpunkt wird jeden Monat langsamer.** Er liefert alle passenden Zeilen. Bei fünfzig Datensätzen zur Veröffentlichung ging das gut, bei zweihunderttausend läuft er ins Zeitlimit. Paginieren Sie ab der ersten Version, mit Standardgröße und einer harten Obergrenze für Clients. Für große oder lebhafte Sammlungen eignet sich ein Cursor besser als ein Offset. Beim Offset schiebt eine zwischen zwei Anfragen eingefügte Zeile eine andere auf die Folgeseite, wo der Client sie erneut liest.\n\n```http\nGET /v1/orders?limit=50\u0026after=ord_8f2c HTTP/1.1\nHost: api.example.com\n```\n\n**Ein Kunde liest den Auftrag eines anderen.** Die API prüft die Anmeldung und lädt `/v1/orders/42` allein über die Kennung. Eine andere Zahl in der Adresse führt durch fremde Daten. Die Authentifizierung beantwortete, wer anruft. Niemand fragte, ob dieser Aufrufer Auftrag 42 besitzt. Begrenzen Sie jede Suche bereits in der Abfrage auf den Eigentümer und behalten Sie einen Test, der als ein Konto Datensätze eines anderen anfordert.\n\n**Die Antwort enthält nie zur Veröffentlichung bestimmte Spalten.** Ein Endpunkt serialisiert eine Datenbankzeile oder ein ORM-Objekt unverändert. Passwort-Hash, internes Flag oder der Einkaufspreis eines Lieferanten gehen damit an jeden Client. Eine nächstes Jahr ergänzte Spalte wird am Tag ihrer Anlage veröffentlicht. Derselbe Fehler auf der Eingabeseite erlaubt, `role` oder `is_admin` einfach im Nachrichtentext zu setzen. Geben Sie jedem Endpunkt ausdrückliche Ein- und Ausgabetypen mit erlaubten Feldern. So wird die Veröffentlichung eines Feldes zu einer bewussten Entscheidung.\n\n## Weiterführende Lektüre\n\n- [RFC 9110: HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110) — die vom IETF definierten Methoden, Statuscodes und Header als Grundlage jeder Web-API.\n- [RFC 9205: Building Protocols with HTTP](https://www.rfc-editor.org/rfc/rfc9205) — aktuelle Empfehlungen für Anwendungen auf HTTP, einschließlich ihrer Weiterentwicklung.\n- [RFC 9457: Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457) — eine standardisierte JSON-Form für Fehlermeldungen, damit Clients Fehler einheitlich auswerten.\n- [RFC 6585: Additional HTTP Status Codes](https://www.rfc-editor.org/rfc/rfc6585) — die Definition von 429 Too Many Requests und dem `Retry-After`-Hinweis für begrenzte Clients.\n- [Semantic Versioning 2.0.0](https://semver.org/) — die Regeln, um inkompatible API-Änderungen über Versionsnummern zu signalisieren.\n\n\u003chttps://engineer.company/de/glossary/api/\u003e\n","date_modified":"2026-11-08T09:42:23Z","description":"Was eine API ist, warum ihr Vertrag den Code überdauert, wie Änderungen Clients nicht beschädigen und welche vier Fehler im Betrieb sichtbar werden","formats":{"gemtext":"https://engineer.company/de/glossary/api/index.gmi","gopher":"https://engineer.company/de/glossary/api/gophermap","html":"https://engineer.company/de/glossary/api/","json":"https://engineer.company/de/glossary/api/index.json","markdown":"https://engineer.company/de/glossary/api/index.md","pdf":"https://engineer.company/de/glossary/api/index.pdf"},"kind":"page","language":"de","title":"Was ist eine API?","url":"https://engineer.company/de/glossary/api/","version":1}