Erste Schritte mit der REST API

Dieser Text wurde mithilfe von KI übersetzt. Wenn du den Originaltext auf Englisch lesen möchtest, klicke hier.

Die WordPress.com REST API ermöglicht es dir, Inhalte auf jeder WordPress.com-Website sowie auf jeder selbst gehosteten (WordPress.org) Website, die über Jetpack verbunden ist, anzuzeigen, zu erstellen oder zu bearbeiten. Dies umfasst nicht nur Blogbeiträge und Seiten, sondern auch Kommentare, Schlagwörter, Kategorien, Medien, Website-Statistiken, Benachrichtigungen, Teilen-Einstellungen, Benutzerprofile und viele weitere WordPress.com-Funktionen.

Einige Anfragen (z. B. das Auflisten öffentlicher Beiträge) erfordern keine Authentifizierung, aber jede Aktion, für die ein Benutzer angemeldet sein müsste (wie das Erstellen eines Beitrags), erfordert ein Authentifizierungstoken.

Um authentifizierte Anfragen zu stellen, musst du zunächst ein Konto auf WordPress.com einrichten, falls du noch keines hast.

Verwendung

Es gibt zwei Möglichkeiten, die verfügbaren Endpunkte der WordPress.com REST API zu erkunden:

• Die REST API Referenzdokumentation listet verfügbare Endpunkte auf und beschreibt die Ein- und Ausgabe jedes einzelnen, zusammen mit Beispielcode in curl und PHP.
• Die REST API Entwicklungskonsole ermöglicht es dir, echte API-Anfragen zu erstellen und auszuprobieren.

Nicht authentifizierte Anfragen zu stellen ist einfach. Da keine speziellen Header erforderlich sind, kannst du diese Anfrage sogar in deinem Browser öffnen, um zu sehen, was sie zurückgibt: https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/?number=2&pretty=true

Authentifizierte Anfragen erfordern einige zusätzliche Schritte. Alle authentifizierten Anfragen an die WordPress.com REST API erfordern ein OAuth2-Zugriffstoken. Dieses Token muss über die OAuth2-Endpunkte von WordPress.com bezogen werden und kann über verschiedene Abläufe erworben werden, wobei die relevantesten folgende sind:

1. Vollständiger OAuth2-Ablauf – Benutzer autorisieren deine Anwendung über die WordPress.com-Oberfläche und gewähren dabei bestimmte Berechtigungen. Dies ist der sicherste Ansatz und für Drittanbieter-Anwendungen erforderlich.
2. Direkter Token-Austausch über Anmeldedaten – Verwende ein Application Password mit grant_type=password, um direkt ein Token für deine eigenen Websites zu erhalten. Dies umgeht den Benutzer-Autorisierungsschritt, erfordert jedoch deine WordPress.com-Anmeldedaten.

Beide Methoden führen zum gleichen Typ von OAuth2-Zugriffstoken, das du in Anfragen als Authorization: Bearer YOUR_ACCESS_TOKEN einfügst. Der tokenbasierte Ansatz gewährleistet konsistente Sicherheit und ermöglicht eine anwendungsspezifische Zugriffskontrolle.

Wir empfehlen die OAuth2-Authentifizierung als sicherste und granularste Methode für den Zugriff auf die WordPress.com REST API. Wenn du bereits mit OAuth2 vertraut bist, kannst du direkt zur technischen Dokumentation springen.

OAuth2 ermöglicht es deiner Anwendung, im Namen eines Benutzers zu handeln, ohne jemals dessen Passwort zu sehen. So funktioniert es: Wenn jemand deine App mit seinem WordPress.com-Konto nutzen möchte, leitet deine App ihn zum Anmelden zu WordPress.com weiter. WordPress.com zeigt ihm genau, was deine App tun möchte (z. B. Beiträge lesen oder neue erstellen) und fragt, ob das in Ordnung ist. Wenn er zustimmt, gibt WordPress.com deiner App ein spezielles Zugriffstoken. Dieses Token ist wie ein temporärer Schlüssel, der deiner App nur die Aktionen erlaubt, denen der Benutzer zugestimmt hat.

Du kannst es dir als ein Drei-Wege-Gespräch vorstellen:

• Benutzer: „Ich möchte über diesen API-Client einen Beitrag erstellen.“
• Client (App): „In Ordnung. Hey, WordPress.com, ich möchte etwas im Namen dieses Benutzers tun. Kannst du ihn fragen, ob das in Ordnung ist?“
• WordPress.com: „Klar. Hey, Benutzer, ist es in Ordnung, wenn der Client in deinem Namen handelt?“
• Benutzer: „Ja, das ist in Ordnung. Ich vertraue diesem Client, in Zukunft Aktionen für mich durchzuführen.“
• WordPress.com: „In Ordnung, Client, hier ist ein Token, das dir erlaubt, Aktionen für diesen Benutzer durchzuführen. Halte es geheim. Halte es sicher.“

Sobald der Client (App) das Token erhalten hat, kann er authentifizierte Anfragen an WordPress.com stellen. So funktioniert eine typische Interaktion:

• Client (App): „Hallo WordPress.com, ich möchte einen neuen Beitrag erstellen. Hier ist mein Zugriffstoken als Nachweis, dass ich berechtigt bin, im Namen des Benutzers zu handeln, zusammen mit dem Beitragstitel, dem Inhalt und weiteren Details.“
• WordPress.com: „Ich habe dein Token überprüft und bestätigt, dass du die Berechtigung zum Erstellen von Beiträgen hast. Der Beitrag wurde erfolgreich erstellt und veröffentlicht. Hier ist die Antwort mit der neuen Beitrags-ID, URL und weiteren Metadaten.“

Dieser tokenbasierte OAuth2-Authentifizierungsworkflow bietet sichere, granulare Zugriffskontrolle – der Client kann nur Aktionen ausführen, die der Benutzer während des OAuth-Ablaufs ausdrücklich autorisiert hat. Das Token kann jederzeit bei Bedarf widerrufen werden, und WordPress.com überprüft die Berechtigungen des Tokens bei jeder Anfrage.

Das Schöne an diesem System ist, dass die Benutzer die Kontrolle behalten. Sie können genau sehen, was deine App anfordert, und den Zugriff jederzeit widerrufen. Deine App speichert niemals Passwörter, und falls ein Token kompromittiert wird, betrifft dies nur den Zugriff dieser einen App – nicht das gesamte Konto des Benutzers.

Das hast du wahrscheinlich schon gesehen, wenn du dich mit deinem Google- oder Facebook-Konto bei Websites anmeldest. Der Vorgang funktioniert auf die gleiche Weise: Du klickst auf „Mit Facebook anmelden“, wirst zur Bestätigung zu Facebook weitergeleitet und dann zurück zur ursprünglichen Website umgeleitet.

Aus Sicht deiner App umfasst der Vorgang einige Schritte:

• Zunächst registrierst du deine Anwendung auf WordPress.com, um eine Client-ID zu erhalten.
• Dann leitest du Benutzer mit einem speziellen Link zu WordPress.com weiter, der deine Client-ID enthält und WordPress.com mitteilt, wohin der Benutzer zurückgeleitet werden soll.
• Wenn Benutzer deine App autorisieren, leitet WordPress.com sie mit einem Autorisierungscode zurück zu deiner App. Du tauschst diesen Code mithilfe deines Client-Secrets gegen ein Access Token ein und kannst dieses Token dann verwenden, um API-Anfragen im Namen des Benutzers zu stellen.

Sobald du ein Access Token hast, ist das Stellen authentifizierter Anfragen unkompliziert. Du fügst das Token im Authorization-Header deiner Anfragen wie folgt ein: Authorization: Bearer your_token_here.

Vollständige Implementierungsdetails, Codebeispiele und bewährte Sicherheitspraktiken findest du im OAuth2-Authentifizierungsleitfaden.

Basis-URL-Struktur

Die WordPress.com REST API bietet eine standardisierte Basis-URL-Struktur, die einen konsistenten Zugriff über alle Website-Typen, Hosting-Konfigurationen und API-Namespaces hinweg gewährleistet. Alle verfügbaren Endpunkte sind unter verschiedenen Namespaces (wie wp, rest und wpcom) und ihren jeweiligen Versionen (wie v1, v1.4, v2, v4) organisiert und gruppiert. Dies ermöglicht eine logische Trennung zwischen verschiedenen API-Funktionalitäten und erlaubt unabhängige Versionierungsstrategien. Dieser einheitliche Ansatz vereinfacht die API-Integration und macht es überflüssig, unterschiedliche URL-Formate basierend auf Website-Eigenschaften oder API-Versionen zu ermitteln.

Detaillierte Informationen zu verfügbaren Namespaces, deren Versionen und welche Endpunkte jeder Namespace bereitstellt, findest du in der Dokumentation zu Namespaces & Versionen.

Allgemeine URL-Struktur

Alle WordPress.com REST API-Endpunkte folgen diesem standardisierten Muster:

https://public-api.wordpress.com/{namespace}/{version}/{endpoint}

Platzhalter:

• {namespace}: Der API-Namespace (z. B. ‚rest‘, ‚wp‘, ‚wpcom‘)
• {version}: Die API-Version (z. B. ‚v1′, ‚v1.4′, ‚v2′, ‚v4′)
• {endpoint}: Der spezifische API-Endpunkt, auf den du zugreifen möchtest

Beispiele:

https://public-api.wordpress.com/rest/v1.4/me
https://public-api.wordpress.com/wpcom/v4/notifications
https://public-api.wordpress.com/wp/v2/posts

Website-spezifische URL-Struktur

Beim Zugriff auf Endpunkte, die sich auf bestimmte WordPress.com-Websites beziehen, enthält die URL-Struktur eine Website-Kennung:

https://public-api.wordpress.com/{namespace}/{version}/sites/{site_id}/{endpoint}

Parameter:

• {namespace}: Der API-Namespace (z. B. ‚rest‘, ‚wp‘, ‚wpcom‘)
• {version}: Die API-Version (z. B. ‚v1′, ‚v1.4′, ‚v2′, ‚v4′)
• {site_id}: Die eindeutige numerische Kennung deiner WordPress.com-Website
• {endpoint}: Der spezifische website-bezogene Endpunkt (z. B. ‚posts‘, ‚pages‘, ‚media‘, ‚users‘)

Beispiele:

https://public-api.wordpress.com/wp/v2/sites/241031857/posts
https://public-api.wordpress.com/rest/v1.4/sites/241031857/stats
https://public-api.wordpress.com/wpcom/v2/sites/241031857/follows

Deine Website-ID ermitteln

Um websitespezifische Endpunkte zu verwenden, musst du die eindeutige numerische Kennung deiner Website ermitteln. Diese Information erhältst du, indem du eine Anfrage an den Endpunkt /rest/v1.1/me/sites über die API-Konsole sendest:

1. Besuche die WordPress.com API-Konsole
2. Navigiere zum Endpunkt /rest/v1.1/me/sites (zu finden unter WP.COM API - v1.1/me/sites in der Konsole)
3. Führe die Anfrage aus, um alle mit deinem Konto verknüpften Websites abzurufen
4. Suche in der Antwort das Feld ID für deine gewünschte Website

Der Endpunkt /rest/v1.1/me/sites gibt umfassende Details zu allen mit deinem WordPress.com-Konto verknüpften Websites zurück, darunter:

• ID: Die eindeutige numerische Website-Kennung (die du für API-Aufrufe benötigst)
• name: Der Anzeigename der Website
• URL: Die öffentliche URL der Website
• jetpack: Ob die Website eine mit Jetpack verbundene Website ist
• is_private: Ob die Website privat ist
• capabilities: Welche Aktionen du auf der Website ausführen kannst

Beispielantwort:

{
  "sites": [
    {
      "ID": 241031857,
      "name": "My Blog",
      "URL": "https://myblog.wordpress.com",
      "jetpack": false,
      "is_private": false,
      "capabilities": {
        "edit_posts": true,
        "publish_posts": true
      }
    }
  ]
}

Alternative URL-Formate

Möglicherweise begegnest du einigen alternativen URL-Formaten:

• Direkter Website-Zugriff, wie https://yoursite.com/wp-json/wp/v2/posts – Dieses Format funktioniert nur bei selbst gehosteten Websites mit Jetpack. Kann aufgrund von Sicherheitseinstellungen, Firewall-Regeln oder Authentifizierungsproblemen fehlschlagen.
• Domain-basierter WordPress.com-Zugriff, wie https://public-api.wordpress.com/wp/v2/sites/yoursite.com/posts – Dieses Format ist unzuverlässig bei Websites mit benutzerdefinierten Domains, DNS-Konfigurationen oder wenn sich Domains ändern.

Um Probleme zu vermeiden, wird empfohlen, das Format mit numerischen Website-IDs zu verwenden, da es zuverlässiger und schneller ist, konsistent über alle Website-Typen hinweg funktioniert und alle WordPress.com-Funktionen sowie Authentifizierungsmethoden unterstützt.

Authentifizierungsanforderungen

Die WordPress.com REST API unterstützt sowohl authentifizierte als auch nicht authentifizierte Anfragen, abhängig vom Endpunkt und den Daten, auf die du zugreifen möchtest. Zu verstehen, wann und wie du dich authentifizieren musst, ist entscheidend für eine erfolgreiche API-Integration.

Nicht authentifizierte Anfragen funktionieren für:

• Öffentliche Website-Informationen (z. B. Website-Details, öffentliche Beiträge)
• Lesen öffentlicher Inhalte von WordPress.com-Websites
• Zugriff auf öffentlich verfügbare Statistiken und Daten

Beispiele für nicht authentifizierte Anfragen:

# Get public information about a site
curl https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/

# Get public posts from a site
curl https://public-api.wordpress.com/wp/v2/sites/en.blog.wordpress.com/posts?per_page=5

Authentifizierung ist erforderlich für:

• Erstellen, Bearbeiten oder Löschen von Inhalten (Beiträge, Seiten, Kommentare)
• Zugriff auf private Websites oder private Inhalte
• Verwalten von Website-Einstellungen und -Konfiguration
• Zugriff auf benutzerspezifische Daten (Benachrichtigungen, gefolgte Websites, persönliche Statistiken)
• Jede Operation, die erfordert, dass man bei WordPress.com direkt angemeldet ist

Beispiele für authentifizierte Anfragen (erfordern ein Token):

# Get your user profile (requires authentication)
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     https://public-api.wordpress.com/rest/v1.4/me

# Create a new post (requires authentication)
curl -X POST 
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     -H "Content-Type: application/json" 
     -d '{"title":"My New Post","content":"This is the post content","status":"publish"}' 
     https://public-api.wordpress.com/wp/v2/sites/YOUR_SITE_ID/posts

# Get your site's stats (requires authentication)
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" 
     https://public-api.wordpress.com/rest/v1.4/sites/YOUR_SITE_ID/stats

Authentifizierungsmethoden

Die gesamte Authentifizierung der WordPress.com REST API ist tokenbasiert. Jede authentifizierte Anfrage erfordert ein OAuth2-Zugriffstoken, das über die OAuth2-Endpunkte von WordPress.com bezogen wird. Die relevantesten Methoden zum Erhalt dieser Tokens sind:

• Direkter Token-Austausch mit Anmeldedaten (für den persönlichen Gebrauch und die Entwicklung)
• Vollständiger OAuth2-Flow (empfohlen für Drittanbieter-Anwendungen)

Direkter Token-Austausch mit Anmeldedaten

Anwendungspasswörter bieten eine Abkürzung, um OAuth2-Zugriffstoken zu erhalten, ohne den vollständigen Benutzerautorisierungs-Flow implementieren zu müssen. Diese Methode verwendet den OAuth2-grant_type=password-Flow, um deinen WordPress.com-Benutzernamen und dein Anwendungspasswort direkt gegen ein Zugriffstoken auszutauschen.

Wann du diese Methode verwenden solltest:

• Persönliche Projekte und Entwicklung
• Kommandozeilen-Tools und Skripte
• Anwendungen, die nur auf deine eigenen WordPress.com-Websites zugreifen
• Testen und Prototyping

So funktioniert es: Anstatt Benutzer über die Autorisierungsoberfläche von WordPress.com weiterzuleiten, verwendest du dein Anwendungspasswort, um direkt ein Token vom OAuth2-Endpunkt anzufordern. Dies umgeht den Schritt der Benutzereinwilligung, erfordert jedoch deine tatsächlichen WordPress.com-Anmeldedaten.

So verwendest du den direkten Token-Austausch per Anmeldedaten:

Um diese Methode zu verwenden, musst du:

• Eine neue WordPress.com-Anwendung erstellen, um die Client-ID und das Client-Secret deiner App zu erhalten.
• Wenn du die Zwei-Faktor-Authentifizierung aktiviert hast (dringend empfohlen), ein neues Anwendungspasswort erstellen. Andernfalls verwende dein reguläres Passwort.

Diese Methode verwendet den OAuth2-Flow grant_type=password, um dein Anwendungspasswort direkt gegen ein Zugriffstoken auszutauschen:

# Step 1: Generate an OAuth2 access token using your Application Password
curl -X POST "https://public-api.wordpress.com/oauth2/token" 
  -d "client_id=<CLIENT_ID>" 
  -d "client_secret=<CLIENT_SECRET>" 
  -d "grant_type=password" 
  -d "username=<USERNAME>" 
  -d "password=<APPLICATION_PASSWORD>"


# Response will contain your access token:
# {
#   "access_token": "your_oauth2_token_here",
#   "token_type": "bearer",
#   "scope": "global"
# }

# Step 2: Use the OAuth2 token for all API requests
curl -X GET 
  'https://public-api.wordpress.com/rest/v1.1/sites/YOUR_SITE_ID/posts' 
  -H 'Authorization: Bearer your_oauth2_token_here' 
  -H 'Content-Type: application/json'

# Create a post using the token
curl -X POST 
  'https://public-api.wordpress.com/wp/v2/sites/YOUR_SITE_ID/posts' 
  -H 'Authorization: Bearer your_oauth2_token_here' 
  -H 'Content-Type: application/json' 
  -d '{"title":"My New Post","content":"Post content here","status":"publish"}'

Wichtige Hinweise:

• Anwendungspasswörter werden niemals direkt mit public-api.wordpress.com-Endpunkten verwendet
• Sie werden nur mit dem OAuth2-Token-Endpunkt verwendet, um Zugriffstoken zu erhalten
• Das resultierende Token ist identisch mit Token, die über den vollständigen OAuth2-Flow erhalten werden
• Alle nachfolgenden API-Anfragen verwenden das OAuth2-Token, nicht das Anwendungspasswort

Vollständiger OAuth2-Flow

Der vollständige OAuth2-Flow ist der empfohlene Ansatz für Drittanbieter-Anwendungen, die eine Autorisierung durch Benutzer für den Zugriff auf deren WordPress.com-Websites und -Daten benötigen. Diese Methode bietet das sicherste und differenzierteste Berechtigungssystem.

Wann du diese Methode verwenden solltest:

• Drittanbieter-Anwendungen, die auf Benutzerdaten zugreifen
• Webanwendungen mit mehreren Benutzern
• Mobile Anwendungen
• Jede App, die benutzergesteuerte Berechtigungen benötigt

So funktioniert es: Benutzer werden zu WordPress.com weitergeleitet, wo sie die spezifischen Berechtigungen, die deine Anwendung anfordert, überprüfen und autorisieren können. Nach der Autorisierung erhält deine Anwendung ein Zugriffstoken, das verwendet werden kann, um API-Anfragen im Namen des Benutzers durchzuführen.

Zusammenfassung des vollständigen OAuth2-Flows:

1. Registriere deine Anwendung bei WordPress.com Apps, um deine Client-ID und dein Secret zu erhalten
2. Leite Benutzer weiter zur Autorisierungs-URL von WordPress.com mit deiner Client-ID und den angeforderten Scopes
3. Der Benutzer überprüft und erteilt die Berechtigung über die Oberfläche von WordPress.com
4. WordPress.com leitet zurück zu deiner App mit einem Autorisierungscode
5. Tausche den Autorisierungscode gegen ein OAuth2-Zugriffstoken unter Verwendung deines Client-Secrets ein
6. Verwende das OAuth2-Zugriffstoken in allen API-Anfragen mit Authorization: Bearer YOUR_TOKEN

Das Ergebnis ist dasselbe OAuth2-Zugriffstoken-Format, das auch von der Methode „Direkter Token-Austausch mit Anmeldedaten“ verwendet wird, was eine konsistente Authentifizierung über beide Ansätze hinweg gewährleistet.

Ausführliche Anleitungen zur OAuth2-Implementierung, einschließlich Codebeispielen und Sicherheitshinweisen, findest du in der Dokumentation zur OAuth2-Authentifizierung.

Fehlerbehebung und Best Practices bei der Authentifizierung

Häufige Authentifizierungsfehler

401 Unauthorized

• Ursache: Ungültiges oder fehlendes Zugriffstoken
• Lösung: Überprüfe, ob dein Token korrekt ist und im Authorization-Header enthalten ist

403 Forbidden

• Ursache: Gültiges Token, aber unzureichende Berechtigungen für die angeforderte Aktion
• Lösung: Überprüfe, ob dein Benutzerkonto über die erforderlichen Berechtigungen für die Website verfügt

Ungültiges Token-Format

• Ursache: Falsches Header-Format
• Lösung: Stelle sicher, dass du Authorization: Bearer YOUR_TOKEN verwendest (beachte das Leerzeichen nach „Bearer“)

Best Practices für die Sicherheit

1. Zugangsdaten niemals in clientseitigem Code offenlegen – Application Passwords sollten nur in serverseitigen Anwendungen verwendet werden
2. Umgebungsvariablen verwenden – Speichere Benutzernamen und Passwörter in Umgebungsvariablen, nicht im Quellcode
3. Passwörter regelmäßig rotieren – Generiere regelmäßig neue Application Passwords und widerrufe alte
4. OAuth2 für benutzerseitige Apps verwenden – Verwende keine Application Passwords für Anwendungen, bei denen sich andere Benutzer authentifizieren
5. Das einheitliche Token-System verstehen – Beide Authentifizierungsmethoden führen zu denselben OAuth2-Zugriffstokens und bieten konsistenten API-Zugriff und Sicherheit
6. Die richtige Methode wählen – Verwende die Application-Password-Kurzform für persönliche Zwecke/Entwicklung und den vollständigen OAuth2-Flow für Drittanbieter-Anwendungen
7. Token-Verwaltung – Tokens können pro Anwendung widerrufen werden, ohne andere Apps zu beeinträchtigen, was eine bessere Sicherheit bietet als das Teilen von Passwörtern

Browserbasierte Anwendungen

Wenn du eine browserbasierte Anwendung erstellst, musst du Folgendes beachten:

1. Verwende den OAuth2 Implicit Flow – Application Passwords sollten nicht in clientseitigem Code verwendet werden
2. Domains auf die Allowlist setzen – Konfiguriere erlaubte Ursprünge in deinen WordPress.com-App-Einstellungen
3. CORS korrekt behandeln – Die API sendet entsprechende CORS-Header für Domains auf der Allowlist

Eine ausführliche Anleitung zu browserbasierten Implementierungen findest du unter Using the REST API from JS and the Browser.

Ressourcen und Dokumentation

• API-Konsole – Interaktives Testen und Erkunden
• API-Referenz – Umfassende Endpoint-Dokumentation
• WordPress REST API Handbook – Offizielle Dokumentation der WordPress Core REST API
• Entwickler-Blog – Updates und Ankündigungen zu API-Änderungen