API-Einführung: Von null an verstehen, wie "Programme miteinander sprechen"

🎯 Kernfrage

Was ist eine API? Das ist wie die Frage: Wie sollte die Speisekarte eines Restaurants gestaltet sein, damit die Gäste sie sofort verstehen? Wie merkt sich der Kellner die Bestellungen, ohne Fehler zu machen? API löst das Problem, wie "Programme miteinander kommunizieren". Du verwendest seit deinem ersten Tag beim Programmieren APIs, auch wenn du es vielleicht nicht bemerkt hast.

0. Drei häufige Verwirrungen für Anfänger

Verwirrung 1: Ist API etwas sehr Kompliziertes?

Viele denken bei API sofort an ein Konzept, das nur fortgeschrittene Ingenieure verstehen können. Tatsächlich hast du schon längst APIs verwendet:

python

len("hello")        # Das ist eine von Python bereitgestellte API
open("file.txt")    # Das ist auch eine API
requests.get(url)   # Das ist ebenfalls eine API

Verwirrung 2: Was ist der Unterschied zwischen Web-API und normaler API?

Typ	Aufrufobjekt	Kommunikationsweise	Typisches Szenario
Funktions-API	Lokaler Code	Funktionsaufruf	`len()`, `open()`
Betriebssystem-API	Betriebssystem	Systemaufruf	Dateien lesen/schreiben, Prozesse erstellen
Web-API	Remote-Server	HTTP-Anfrage	KI-Modelle aufrufen, Wetterdaten abrufen

Verwirrung 3: Soll ich HTTP oder SDK verwenden?

python

# HTTP-Methode: Alle Details selbst behandeln
import requests
response = requests.post(
    "https://api.deepseek.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-xxx"},
    json={"model": "deepseek-chat", "messages": [...]}
)
result = response.json()["choices"][0]["message"]["content"]

# SDK-Methode: Der Butler erledigt alles für dich
from openai import OpenAI
client = OpenAI(api_key="sk-xxx")
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[...]
)
result = response.choices[0].message.content

1. Die Essenz der API: Stecker und Steckdose

API (Application Programming Interface, Schnittstelle zur Anwendungsprogrammierung) ist die "Vereinbarung für die Kommunikation zwischen Programmen".

1.1 Analogie mit Elektrogeräten

Konzept	Elektro-Analogie	API-Entsprechung
Schnittstelle	Steckdosenform	Funktionssignatur / URL
Eingabe	Stromversorgung	Funktionsparameter / Anfragekörper
Ausgabe	Gerät arbeitet	Rückgabewert / Antwortkörper

1.2 Vergleich von drei API-Formen

TargetLocal code library

CommunicationFunction call

LatencyNanoseconds

Typical scenariosData processing, file operations

Function API example

len("hello")           # returns 5
max([1, 5, 3])         # returns 5
open("file.txt").read() # reads a file

1.3 Unterschied zwischen Funktions-API und HTTP-API

Viele Anfänger sind verwirrt: Was ist eigentlich der Unterschied zwischen einer Funktions-API und einer HTTP-API? Wie unterscheidet man sie in der Dokumentation?

📚 Function API vs HTTP APILocal calls vs network requests: how should you read the docs?

📦Function API

Call styleDirect function call

ParametersArguments inside parentheses

Return valueReturn value directly

Error handlingException or return value

Python example

# Call a built-in function
length = len("hello")      # returns 5

# Call a library function
import math
result = math.sqrt(16)     # returns 4.0

# Call a custom function
def add(a, b):
    return a + b
sum = add(3, 5)            # returns 8

🌐HTTP API

Call styleNetwork request

ParametersURL / body / headers

Return valueJSON/XML response

Error handlingStatus code checks

HTTP request example

POST /v1/chat/completions HTTP/1.1
Host: api.deepseek.com
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "model": "deepseek-chat",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}

Core point:A function API works locally; an HTTP API communicates remotely. Function docs focus on parameters and return values, while HTTP API docs focus on endpoint, authentication, and request/response formats.

1.4 Wie liest man verschiedene Arten von API-Dokumentation

Bei verschiedenen Arten von API-Dokumentation sind die Schwerpunkte unterschiedlich:

📋 How to Read Different Doc TypesFunction docs, REST API docs, and SDK docs each emphasize different things

Doc typeFunction docs

Best forUsing standard library or third-party functions

Difficulty⭐⭐

🔍 What to focus on

Function signatureParameter typesReturn valueExceptionsExample code

📝Doc example

### json.loads(s, *, cls=None, object_hook=None...)

Parse a JSON string into a Python object.

**Parameters:**
- s (str): JSON string to parse
- cls (JSONDecoder): Custom decoder class
- object_hook (callable): Optional conversion function

**Returns:**
- dict | list: Parsed Python object

**Raises:**
- JSONDecodeError: The string is invalid JSON

**Example:**
>>> import json
>>> json.loads('{"name": "Alice"}')
{'name': 'Alice'}

💡Reading tips

Read the function signature first to see what parameters are needed.
Check parameter types and whether each parameter is required.
Check the return type so later code can handle it correctly.
Notice possible exceptions and prepare error handling.

📊Quick comparison of three doc types

Item

Function docs

REST API docs

SDK docs

Core focus

Parameters, return values

Endpoint, request body

Initialization, method chain

Code example

Function call

HTTP request

Object method

Error handling

Exceptions/return values

Status codes

Exception objects

Read first

Function signature

Base URL + Auth

Quick Start

Reading advice:For function docs, read the signature. For API docs, read the request format. For SDK docs, read examples first. When stuck, look for Quick Start or Getting Started.

2. Ein vollständiger API-Aufruf

👇 Probier es aus: Klicke auf die Schaltfläche unten und beobachte einen vollständigen API-Anfrage-Antwort-Ablauf:

API Request Demo

// Click a command below to simulate API requests

> ▋

💻ClientSends request

Waiting for request...

HTTP Request→

🖥️ServerHandles request

Waiting...

HTTP Response←

📦ResponseReturns result

Waiting for response...

💡 Click a command button to observe a complete API request-response flow.

2.1 Die vier Phasen eines API-Aufrufs

Phase	Was passiert	Elektro-Analogie
Anfrage	Client sendet Anfrage an den Server	Schalter drücken
Übertragung	Anfrage wird über das Netzwerk zum Server übertragen	Strom fließt durch das Kabel
Verarbeitung	Server verarbeitet die Anfrage und gibt Daten zurück	Gerät beginnt zu arbeiten
Antwort	Client empfängt und verarbeitet das zurückgegebene Ergebnis	Glühbirne leuchtet

2.2 Restaurant-Analogie

Restaurant-Rolle	API-Entsprechung	Beschreibung
Speisekarte	API-Dokumentation	Sagt dir, welche "Gerichte" bestellt werden können
Kellner	HTTP-Protokoll	Standardisierte "Kommunikationsweise"
Küche	Server	Verarbeitet "Bestellungen"
Servieren	Antwort	Liefert das Ergebnis an den "Gast"

3. HTTP-Methoden: Fragst du oder tust du?

Beim Aufrufen einer Web-API musst du dem Server mitteilen, was du tun möchtest. Dafür gibt es HTTP-Methoden.

3.1 Mit der Restaurantbestellung verstehen

Szenario	Was würdest du in der Realität sagen?	Entsprechende HTTP-Methode
Du möchtest wissen, was es heute gibt	"Kellner, bringen Sie mir die Speisekarte"	GET - Nur "fragen", keine Daten ändern
Du möchtest Kung Pao Huhn bestellen	"Ich hätte gerne Kung Pao Huhn"	POST - Etwas "tun", Daten erstellen
Du möchtest ein Gericht ändern	"Bitte das Kung Pao Huhn durch Süß-Sauer Fisch ersetzen"	PUT - Daten ersetzen
Du möchtest den Geschmack ändern	"Kung Pao Huhn bitte ohne Erdnüsse"	PATCH - Teilweise Änderung
Du möchtest es nicht mehr	"Lassen Sie das Gericht weg"	DELETE - Daten löschen

get

Read

Query data

Idempotent

post

Create

Add data

Not idempotent

put

Full update

Replace resource

Idempotent

patch

Partial update

Modify fields

Not idempotent

delete

Delete

Remove resource

Idempotent

getRead - Query data

Fetch resources from the server without changing data

Restaurant analogy:"Waiter, show me the menu"

GET /api/users           # fetch user list
GET /api/users/123       # fetch one user
GET /api/products?cat=phone  # query phone products

Zur Idempotenz

Idempotenz: Führt mehrmalige Ausführung zum gleichen Ergebnis?

Idempotente Operationen (GET/PUT/DELETE): 10 Mal klicken hat das gleiche Ergebnis wie 1 Mal
Nicht-idempotente Operationen (POST): 10 Mal klicken kann 10 Bestellungen erstellen

Lösung: POST-Operationen mit eindeutiger ID überprüfen, um doppelte Verarbeitung zu vermeiden.

3.2 HTTP-Methoden-Schnellreferenz

Methode	Zweck	Idempotenz	Sicherheit	Typische Szenarien
GET	Ressource abrufen	Ja	Ja	Listen abfragen, Details anzeigen
POST	Ressource erstellen	Nein	Nein	Neuen Benutzer anlegen, Bestellung aufgeben
PUT	Vollständige Aktualisierung	Ja	Nein	Gesamte Benutzerdaten ersetzen
PATCH	Teilaktualisierung	Nein	Nein	Nur den Spitznamen ändern
DELETE	Ressource löschen	Ja	Nein	Benutzer löschen, Bestellung stornieren

4. HTTP-Statuscodes: Was dir der Server mitteilt

Wenn der Server antwortet, gibt er zuerst einen Statuscode zurück, der dir mitteilt, ob die Anfrage erfolgreich war.

4.1 Statuscode-Kategorien

2xxSuccess

The request was received, understood, and processed successfully

200 OK201 Created204 No Content

3xxRedirect

More action is needed to complete the request

301 Moved Permanently304 Not Modified307 Temporary Redirect

4xxClient error

The request has an error or cannot be completed

400 Bad Request401 Unauthorized403 Forbidden404 Not Found

5xxServer error

The server failed to handle a valid request

500 Internal Error502 Bad Gateway503 Unavailable

💡Memory tip:2️⃣ Success • 3️⃣ Redirect • 4️⃣ Client error • 5️⃣ Server error

4.2 Häufige Statuscodes im Detail

Statuscode	Bedeutung	Typisches Szenario	Client-Behandlung
200 OK	Erfolg	Anfrage erfolgreich verarbeitet	Daten anzeigen
201 Created	Erstellt	POST-Anfrage hat Ressource erfolgreich erstellt	Zur neuen Ressource navigieren
400 Bad Request	Anfrageformat fehlerhaft	Parameter fehlen oder Format falsch	Parameter überprüfen
401 Unauthorized	Nicht authentifiziert	Kein gültiger API-Key bereitgestellt	Benutzer zur Anmeldung auffordern
403 Forbidden	Keine Berechtigung	API-Key hat keine Zugriffsberechtigung auf diese Ressource	Auf unzureichende Berechtigungen hinweisen
404 Not Found	Nicht vorhanden	Angeforderte Adresse oder Ressource existiert nicht	URL überprüfen
429 Too Many Requests	Zu viele Anfragen	Ratenlimit überschritten	Später erneut versuchen
500 Internal Server Error	Serverfehler	Serverseitiges Problem	Benutzer auffordern, es später erneut zu versuchen

👇 Probier es aus: Klicke auf die Schaltfläche unten, um die Bedeutung häufiger Statuscodes zu verstehen:

HTTP Status Code Demo

// Click a button to inspect status code meanings

> ▋

✅2xx Success

200OKRequest succeeded

201CreatedResource created

204No ContentSucceeded with no response body

⚠️4xx Client errors

400Bad RequestMalformed request

401UnauthorizedNot authenticated

403ForbiddenNo permission

404Not FoundResource missing

422UnprocessableSemantic validation error

429Too ManyToo many requests

🔴5xx Server errors

500Server ErrorInternal server error

502Bad GatewayGateway error

503UnavailableService unavailable

💡 Click a command button to learn common HTTP status codes.

5. HTTP vs SDK: Selbst erledigen oder den Butler schicken?

5.1 Vergleich der beiden Aufrufmethoden

	🏃 HTTP-API	🤵 SDK
Analogie	Selbst erledigen	Butler erledigt es
Vorteile	✓ Von allen Sprachen nutzbar ✓ Vollständige Kontrolle über Anfragedetails ✓ Keine zusätzlichen Abhängigkeiten	✓ Code ist prägnant und lesbar ✓ Automatische Authentifizierungsverarbeitung ✓ Eingebaute Fehler-Wiederholung
Nachteile	✗ Alle Details selbst behandeln ✗ Code ist lang und fehleranfällig	✗ Abhängigkeit muss installiert werden ✗ Mögliche Versionsprobleme
Code-Beispiel	`requests.post(url, json=..., headers={...})`	`client.chat.completions.create(...)`

5.2 Wie wählen?

Szenario	Empfohlene Methode	Grund
Schnelle Entwicklung	SDK	Automatische Authentifizierung, Fehlerbehandlung, Wiederholung
Prinzipien lernen	HTTP	Zugrundeliegende Mechanismen verstehen
Nicht unterstützte Sprache	HTTP	Von jeder Sprache nutzbar
Anpassung erforderlich	HTTP	Flexible Kontrolle über jedes Detail

💡 Empfehlung

SDK verwenden, wenn möglich, die lästigen Aufgaben der Bibliothek überlassen und die Zeit für sich selbst nutzen.

6. Wie liest man API-Dokumentation?

API-Dokumentation ist wie eine Kombination aus Bedienungsanleitung und Speisekarte. Du musst sie nicht von vorne bis hinten lesen, sondern nur lernen, "im Wörterbuch nachzuschlagen".

6.1 Checkliste für die Dokumentation

Öffne eine beliebige API-Dokumentation (z.B. OpenAI oder DeepSeek) und suche nur nach diesen Dingen:

📖API Document Translator

Base URL

https://api.deepseek.com

Endpoint

POST /v1/chat/completions

Headers

Authorization: Bearer sk-xxx
Content-Type: application/json

Body parameters

modelRequiredModel name

messagesRequiredConversation messages

temperatureOptional0-2, default 1

Translate into code

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxx",
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}]
)

Core idea:When reading docs, find three things: address (Base URL), authentication (Authorization), and parameters.

Element	Beschreibung	Beispiel
Base URL	Die Stammadresse der API	`https://api.deepseek.com`
Authentication	Wie man seine Identität nachweist	`Authorization: Bearer sk-xxx`
Endpoints	Die konkrete Liste der Schnittstellen	`/v1/chat/completions`
Parameters	Pflicht-/Optionale Parameter	`model` (Pflicht), `temperature` (Optional)
Response	Rückgabedatenstruktur	`{"choices": [...]}`

6.2 Schritte zum Lesen der Dokumentation

Base URL finden - Das ist das Präfix für alle Anfragen
Authentifizierungsmethode verstehen - API-Key im Header oder Query?
Benötigten Endpoint finden - Die konkrete Schnittstelle, die du aufrufen möchtest
Anfrageparameter prüfen - Welche sind Pflicht? Welche optional?
Rückgabeformat verstehen - Wie sind die Daten organisiert?

7. Praxisübung: API-Aufruf simulieren

Reden allein hilft nicht. Hier ist eine simulierte API, bei der du Parameter und Adresse frei ausfüllen und ändern kannst, um zu sehen, was passiert.

🧪API PlaygroundTry calls without touching a real server

Endpoint

Method

API Key

Send a request to see the response

Quick tries:

Versuche, folgende Szenarien auszulösen:

✅ Erfolgreiche Anfrage: Korrekten Endpoint und API-Key eingeben
❌ 401-Fehler: Keinen API-Key eingeben und sehen, wie der Server dich abweist
❌ 404-Fehler: Eine nicht existierende Adresse eingeben

8. Zusammenfassung

Kernpunkte

API ist ein Sprachrohr, das deine Worte an einen anderen Codeabschnitt oder Remote-Server weitergibt
Du hast schon längst APIs verwendet, von len() bis open() sind alles APIs
Web-APIs sind Superkräfte, die dich Supercomputer Tausende von Kilometern entfernt aufrufen lassen
SDKs sind gute Butler, wenn du ein SDK verwenden kannst, erledige die Aufgaben nicht selbst
Bei der Dokumentation drei Dinge suchen: Adresse, Authentifizierung, Parameter

Im Zeitalter der KI-Programmierung musst du dir nur diese wenigen Kernkonzepte merken. Die restlichen Details werden von IDE und KI-Assistenten für dich erledigt.

Glossar

Begriff	Vollständige Bezeichnung	Erklärung
API	Application Programming Interface	Schnittstelle zur Anwendungsprogrammierung, definiert, wie Software miteinander interagiert
Web-API	-	Auf dem HTTP-Protokoll basierende API für die Netzwerkkommunikation
Endpoint	-	Endpunkt, die konkrete Adresse einer API
HTTP	HyperText Transfer Protocol	Das von Web-APIs verwendete Kommunikationsprotokoll
GET	-	Methode zum Abrufen von Ressourcen
POST	-	Methode zum Übermitteln von Daten
SDK	Software Development Kit	Software-Entwicklungskit, kapselt Low-Level-API-Aufrufe
URL	Uniform Resource Locator	Netzwerkadresse einer API
JSON	JavaScript Object Notation	Häufig verwendetes Datenformat
Authentication	-	Prozess der Identitätsüberprüfung
Status Code	-	Statuscode in einer HTTP-Antwort
Request	-	Anfrage
Response	-	Antwort
Header	-	HTTP-Header, enthält Metainformationen
Payload	-	Die tatsächlichen Daten einer Anfrage oder Antwort
Rate Limit	-	Ratenbegrenzung
Idempotent	-	Idempotenz, mehrmalige Ausführung führt zum gleichen Ergebnis
REST	Representational State Transfer	Ein API-Architekturstil
RPC	Remote Procedure Call	Entfernter Prozeduraufruf
GraphQL	-	Eine Abfragesprache-API
gRPC	-	Ein von Google entwickeltes Hochleistungs-RPC-Framework

API-Einführung: Von null an verstehen, wie "Programme miteinander sprechen" ​

0. Drei häufige Verwirrungen für Anfänger ​

1. Die Essenz der API: Stecker und Steckdose ​

1.1 Analogie mit Elektrogeräten ​

1.2 Vergleich von drei API-Formen ​

1.3 Unterschied zwischen Funktions-API und HTTP-API ​

1.4 Wie liest man verschiedene Arten von API-Dokumentation ​

2. Ein vollständiger API-Aufruf ​

2.1 Die vier Phasen eines API-Aufrufs ​

2.2 Restaurant-Analogie ​

3. HTTP-Methoden: Fragst du oder tust du? ​

3.1 Mit der Restaurantbestellung verstehen ​

3.2 HTTP-Methoden-Schnellreferenz ​

4. HTTP-Statuscodes: Was dir der Server mitteilt ​

4.1 Statuscode-Kategorien ​

4.2 Häufige Statuscodes im Detail ​

5. HTTP vs SDK: Selbst erledigen oder den Butler schicken? ​

5.1 Vergleich der beiden Aufrufmethoden ​

5.2 Wie wählen? ​

6. Wie liest man API-Dokumentation? ​

6.1 Checkliste für die Dokumentation ​

6.2 Schritte zum Lesen der Dokumentation ​

7. Praxisübung: API-Aufruf simulieren ​

8. Zusammenfassung ​

Glossar ​

API-Einführung: Von null an verstehen, wie "Programme miteinander sprechen"

0. Drei häufige Verwirrungen für Anfänger

1. Die Essenz der API: Stecker und Steckdose

1.1 Analogie mit Elektrogeräten

1.2 Vergleich von drei API-Formen

1.3 Unterschied zwischen Funktions-API und HTTP-API

1.4 Wie liest man verschiedene Arten von API-Dokumentation

2. Ein vollständiger API-Aufruf

2.1 Die vier Phasen eines API-Aufrufs

2.2 Restaurant-Analogie

3. HTTP-Methoden: Fragst du oder tust du?

3.1 Mit der Restaurantbestellung verstehen

3.2 HTTP-Methoden-Schnellreferenz

4. HTTP-Statuscodes: Was dir der Server mitteilt

4.1 Statuscode-Kategorien

4.2 Häufige Statuscodes im Detail

5. HTTP vs SDK: Selbst erledigen oder den Butler schicken?

5.1 Vergleich der beiden Aufrufmethoden

5.2 Wie wählen?

6. Wie liest man API-Dokumentation?

6.1 Checkliste für die Dokumentation

6.2 Schritte zum Lesen der Dokumentation

7. Praxisübung: API-Aufruf simulieren

8. Zusammenfassung

Glossar