Aan de slag met de REST API

Deze tekst is vertaald met AI. Als je de oorspronkelijke tekst in het Engels wilt bekijken, klik hier.

Met de WordPress.com REST API kun je content bekijken, aanmaken of bewerken op elke WordPress.com-site, evenals op elke zelfgehoste (WordPress.org)-site die is verbonden via Jetpack. Dit omvat niet alleen blogberichten en pagina’s, maar ook reacties, tags, categorieën, media, sitestatistieken, meldingen, instellingen voor delen, gebruikersprofielen en veel andere WordPress.com-functies.

Sommige aanvragen (bijv. het weergeven van openbare berichten) hoeven niet te worden geauthenticeerd, maar elke actie waarvoor een gebruiker ingelogd moet zijn (zoals het aanmaken van een bericht), vereist een authenticatietoken.

Om geauthenticeerde aanvragen te doen, moet je eerst een account instellen op WordPress.com als je er nog geen hebt.

Hoe je het gebruikt

Er zijn twee manieren om de beschikbare endpoints voor de WordPress.com REST API te verkennen:

• De documentatiepagina met de REST API Reference vermeldt de beschikbare endpoints en beschrijft de invoer en uitvoer van elk endpoint, samen met voorbeeldcode in curl en PHP.
• Met de ontwikkelconsole voor de REST API kun je echte API-aanvragen opbouwen en uitproberen.

Niet-geauthenticeerde aanvragen doen is eenvoudig. Omdat er geen speciale headers nodig zijn, kun je deze zelfs in je browser openen om te zien wat er wordt geretourneerd: https://public-api.wordpress.com/rest/v1.1/sites/en.blog.wordpress.com/posts/?number=2&pretty=true

Geauthenticeerde aanvragen doen vereist een paar extra stappen. Alle geauthenticeerde aanvragen naar de WordPress.com REST API vereisen een OAuth2 access token. Dit token moet worden verkregen via de OAuth2-endpoints van WordPress.com en kan via verschillende flows worden verkregen, waarvan de meest relevante zijn:

1. Volledige OAuth2-flow – Gebruikers autoriseren je applicatie via de interface van WordPress.com en verlenen specifieke rechten. Dit is de veiligste aanpak en vereist voor applicaties van derden.
2. Directe tokenuitwisseling met inloggegevens – Gebruik een Application Password met grant_type=password om direct een token voor je eigen sites te verkrijgen. Hiermee sla je de stap voor gebruikersautorisatie over, maar je WordPress.com-inloggegevens zijn wel vereist.

Beide methoden leveren hetzelfde type OAuth2-toegangstoken op, dat je in aanvragen opneemt als Authorization: Bearer YOUR_ACCESS_TOKEN. De tokengebaseerde aanpak zorgt voor consistente beveiliging en maakt toegangsbeheer per applicatie mogelijk.

We raden OAuth2-authenticatie aan als de veiligste en meest gedetailleerde manier om toegang te krijgen tot de WordPress.com REST API. Als je al bekend bent met OAuth2, kun je direct doorgaan naar de technische documentatie.

Met OAuth2 kan je applicatie namens een gebruiker handelen zonder ooit diens wachtwoord te zien. Zo werkt het: wanneer iemand je app wil gebruiken met diens WordPress.com-account, stuurt je app diegene naar WordPress.com om in te loggen. WordPress.com laat precies zien wat je app wil doen (zoals berichten lezen of nieuwe berichten maken) en vraagt of dat oké is. Als de gebruiker ja zegt, geeft WordPress.com je app een speciaal toegangstoken. Dit token is als een tijdelijke sleutel waarmee je app alleen de dingen kan doen waarmee de gebruiker heeft ingestemd.

Je kunt het zien als een gesprek tussen drie partijen:

• Gebruiker: “Ik wil graag een bericht maken via deze API-client.”
• Client (app): “Oké. Hoi WordPress.com, ik wil graag iets doen namens deze gebruiker. Kun je vragen of dat oké is?”
• WordPress.com: “Natuurlijk. Hoi gebruiker, is het oké als Client namens jou handelt?”
• Gebruiker: “Ja, dat is oké. Ik vertrouw erop dat deze client in de toekomst acties voor mij uitvoert.”
• WordPress.com: “Oké, Client, hier is een token waarmee je acties voor deze gebruiker kunt uitvoeren. Houd het geheim. Bewaar het veilig.”

Zodra de Client (app) het token heeft verkregen, kan deze geauthenticeerde aanvragen doen bij WordPress.com. Zo werkt een typische interactie:

• Client (app): “Hallo WordPress.com, ik wil graag een nieuw bericht maken. Hier is mijn toegangstoken waarmee ik bewijs dat ik gemachtigd ben om namens de gebruiker te handelen, samen met de titel, inhoud en andere details van het bericht.”
• WordPress.com: “Ik heb je token gevalideerd en bevestigd dat je toestemming hebt om berichten te maken. Het bericht is succesvol gemaakt en gepubliceerd. Hier is de reactie met het nieuwe bericht-ID, de URL en andere metadata.”

Deze OAuth2-workflow voor tokengebaseerde authenticatie biedt veilige, gedetailleerde toegangscontrole: de Client kan alleen acties uitvoeren die de gebruiker expliciet heeft geautoriseerd tijdens de OAuth-flow. Het token kan indien nodig op elk moment worden ingetrokken en WordPress.com valideert de rechten van het token bij elke aanvraag.

Het mooie van dit systeem is dat gebruikers de controle houden. Ze kunnen precies zien waar je app om vraagt en ze kunnen de toegang op elk moment intrekken. Je app slaat nooit wachtwoorden op, en als een token wordt gecompromitteerd, heeft dat alleen invloed op de toegang van die ene app, niet op het volledige account van de gebruiker.

Je hebt dit waarschijnlijk al eens gezien wanneer je inlogt op websites met je Google- of Facebook-account. Het proces werkt op dezelfde manier: je klikt op “Log in with Facebook” (Inloggen met Facebook), wordt naar Facebook gestuurd om te bevestigen en wordt daarna teruggeleid naar de oorspronkelijke site.

Vanuit het perspectief van je app bestaat het proces uit een paar stappen:

• Eerst registreer je je applicatie op WordPress.com om een client-ID te krijgen.
• Vervolgens stuur je gebruikers naar WordPress.com met een speciale link die je client-ID bevat en WordPress.com vertelt waar de gebruiker naar teruggestuurd moet worden.
• Wanneer gebruikers je app autoriseren, leidt WordPress.com ze terug naar je app met een autorisatiecode. Je wisselt deze code in voor een toegangstoken met je clientgeheim, waarna je die token kunt gebruiken om API-verzoeken namens de gebruiker te doen.

Zodra je een toegangstoken hebt, is het eenvoudig om geauthenticeerde verzoeken te doen. Je neemt de token op in de Authorization-header van je verzoeken, zoals hier: Authorization: Bearer your_token_here.

Bekijk voor volledige implementatiedetails, codevoorbeelden en best practices voor beveiliging de handleiding voor OAuth2-authenticatie.

Structuur van de basis-URL

De WordPress.com REST API biedt een gestandaardiseerde structuur voor de basis-URL die consistente toegang garandeert voor alle sitetypen, hostingconfiguraties en API-naamruimten. Alle beschikbare endpoints zijn georganiseerd en gegroepeerd onder verschillende naamruimten (zoals wp, rest en wpcom) en hun respectieve versies (zoals v1, v1.4, v2, v4), wat zorgt voor een logische scheiding tussen verschillende API-functionaliteiten en onafhankelijke versiebeheerstrategieën mogelijk maakt. Deze uniforme aanpak vereenvoudigt API-integratie en maakt het overbodig om verschillende URL-indelingen te bepalen op basis van sitekenmerken of API-versies.

Zie de documentatie over naamruimten en versies voor gedetailleerde informatie over beschikbare naamruimten, hun versies en welke endpoints elke naamruimte biedt.

Algemene URL-structuur

Alle endpoints van de WordPress.com REST API volgen dit gestandaardiseerde patroon:

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

Plaatshouders:

• {namespace}: De API-namespace (bijv. ‘rest’, ‘wp’, ‘wpcom’)
• {version}: De API-versie (bijv. ‘v1’, ‘v1.4’, ‘v2’, ‘v4’)
• {endpoint}: Het specifieke API-endpoint waartoe je toegang wilt

Voorbeelden:

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

Sitespecifieke URL-structuur

Wanneer je endpoints opent die werken op specifieke WordPress.com-sites, bevat de URL-structuur een site-ID:

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

Parameters:

• {namespace}: De API-namespace (bijv. ‘rest’, ‘wp’, ‘wpcom’)
• {version}: De API-versie (bijv. ‘v1’, ‘v1.4’, ‘v2’, ‘v4’)
• {site_id}: De unieke numerieke ID van je WordPress.com-site
• {endpoint}: Het specifieke sitegerelateerde endpoint (bijv. ‘posts’, ‘pages’, ‘media’, ‘users’)

Voorbeelden:

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

Je site-ID verkrijgen

Om sitespecifieke endpoints te gebruiken, moet je de unieke numerieke identifier van je site verkrijgen. Je kunt deze info ophalen door een request te doen naar het endpoint /rest/v1.1/me/sites vanuit de API Console:

1. Ga naar de WordPress.com API Console
2. Navigeer naar het endpoint /rest/v1.1/me/sites (dat je kunt vinden bij WP.COM API - v1.1/me/sites in de Console)
3. Voer de request uit om alle sites op te halen die aan je account zijn gekoppeld
4. Zoek het veld ID in de respons voor de gewenste site

Het endpoint /rest/v1.1/me/sites retourneert uitgebreide gegevens over alle sites die aan je WordPress.com-account zijn gekoppeld, waaronder:

• ID: De unieke numerieke site-identifier (die je nodig hebt voor API-calls)
• name: De weergavenaam van de site
• URL: De openbare URL van de site
• jetpack: Of de site een met Jetpack verbonden site is
• is_private: Of de site privé is
• capabilities: Welke acties je op de site kunt uitvoeren

Voorbeeldrespons:

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

Alternatieve URL-indelingen

Je kunt enkele alternatieve URL-indelingen tegenkomen:

• Directe sitetoegang, zoals https://yoursite.com/wp-json/wp/v2/posts – Deze indeling werkt alleen voor zelf-gehoste sites met Jetpack. Kan mislukken door beveiligingsinstellingen, firewallregels of authenticatieproblemen.
• Domeingebaseerde WordPress.com-toegang, zoals https://public-api.wordpress.com/wp/v2/sites/yoursite.com/posts – Deze indeling is onbetrouwbaar voor sites met aangepaste domeinen, DNS-configuraties of wanneer domeinen wijzigen.

Om problemen te voorkomen, is de aanbevolen aanpak om de indeling met numerieke site-ID’s te gebruiken. Die is betrouwbaarder en sneller, werkt consistent voor alle sitetypen en ondersteunt alle WordPress.com-functies en authenticatiemethoden.

Authenticatievereisten

De WordPress.com REST API ondersteunt zowel geauthenticeerde als niet-geauthenticeerde aanvragen, afhankelijk van het endpoint en de gegevens waartoe je toegang probeert te krijgen. Begrijpen wanneer en hoe je moet authenticeren is essentieel voor een geslaagde API-integratie.

Niet-geauthenticeerde aanvragen werken voor:

• Openbare site-informatie (bijv. sitegegevens, openbare berichten)
• Openbare content lezen van WordPress.com-sites
• Toegang tot openbaar beschikbare statistieken en gegevens

Voorbeelden van niet-geauthenticeerde aanvragen:

# 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

Authenticatie is vereist voor:

• Content maken, bewerken of verwijderen (berichten, pagina’s, reacties)
• Toegang krijgen tot privésites of privécontent
• Site-instellingen en configuratie beheren
• Toegang krijgen tot gebruikersspecifieke gegevens (meldingen, gevolgde sites, persoonlijke statistieken)
• Elke bewerking waarvoor een gebruiker ingelogd moet zijn wanneer WordPress.com rechtstreeks wordt gebruikt

Voorbeelden van geauthenticeerde aanvragen (vereisen een 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

Authenticatiemethoden

Alle authenticatie voor de WordPress.com REST API is op tokens gebaseerd. Elke geauthenticeerde aanvraag vereist een OAuth2-toegangstoken dat is verkregen via de OAuth2-endpoints van WordPress.com. De meest relevante methoden om deze tokens te verkrijgen zijn:

• Directe tokenuitwisseling met inloggegevens (voor persoonlijk gebruik en ontwikkeling)
• Volledige OAuth2-flow (aanbevolen voor applicaties van derden)

Directe tokenuitwisseling met inloggegevens

Applicatiewachtwoorden bieden een snelkoppeling om OAuth2-toegangstokens te verkrijgen zonder de volledige gebruikersautorisatieflow te implementeren. Deze methode gebruikt de OAuth2-flow grant_type=password om je WordPress.com-gebruikersnaam en applicatiewachtwoord rechtstreeks in te wisselen voor een toegangstoken.

Wanneer je deze methode gebruikt:

• Personal-projecten en ontwikkeling
• Command-line tools en scripts
• Applicaties die alleen toegang hebben tot je eigen WordPress.com-sites
• Testen en prototypen

Hoe het werkt: In plaats van gebruikers om te leiden via de autorisatie-interface van WordPress.com, gebruik je je applicatiewachtwoord om rechtstreeks een token aan te vragen bij het OAuth2-endpoint. Hiermee sla je de stap voor gebruikerstoestemming over, maar zijn je daadwerkelijke WordPress.com-inloggegevens vereist.

Zo gebruik je de directe tokenuitwisseling met inloggegevens:

Om deze methode te gebruiken, moet je het volgende doen:

• Maak een nieuwe WordPress.com-applicatie om de Client ID en Client Secret van je app te verkrijgen.
• Als je tweefactorauthenticatie hebt ingeschakeld (sterk aanbevolen), maak dan een nieuw applicatiewachtwoord aan. Gebruik anders je gewone wachtwoord.

Deze methode gebruikt de OAuth2-flow grant_type=password om je applicatiewachtwoord rechtstreeks in te wisselen voor een toegangstoken:

# 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"}'

Belangrijkste punten:

• Applicatiewachtwoorden worden nooit rechtstreeks gebruikt met public-api.wordpress.com-endpoints
• Ze worden alleen gebruikt met het OAuth2-tokenendpoint om toegangstokens te verkrijgen
• Het resulterende token is identiek aan tokens die via de volledige OAuth2-flow zijn verkregen
• Alle volgende API-aanvragen gebruiken het OAuth2-token, niet het applicatiewachtwoord

Volledige OAuth2-flow

De volledige OAuth2-flow is de aanbevolen aanpak voor applicaties van derden waarbij gebruikers toegang tot hun WordPress.com-sites en -gegevens moeten autoriseren. Deze methode biedt het veiligste en meest gedetailleerde machtigingensysteem.

Wanneer je deze methode gebruikt:

• Applicaties van derden die toegang hebben tot gebruikersgegevens
• Webapplicaties met meerdere gebruikers
• Mobiele applicaties
• Elke app die door de gebruiker beheerde machtigingen nodig heeft

Hoe het werkt: Gebruikers worden doorgestuurd naar WordPress.com, waar ze de specifieke machtigingen die je applicatie aanvraagt kunnen bekijken en autoriseren. Na autorisatie ontvangt je applicatie een toegangstoken dat kan worden gebruikt om namens de gebruiker API-aanvragen te doen.

Samenvatting van de volledige OAuth2-flow:

1. Registreer je applicatie bij WordPress.com Apps om je client-ID en clientgeheim te krijgen
2. Stuur gebruikers door naar de autorisatie-URL van WordPress.com met je client-ID en aangevraagde scopes
3. De gebruiker bekijkt en verleent toestemming via de interface van WordPress.com
4. WordPress.com stuurt terug naar je app met een autorisatiecode
5. Wissel de autorisatiecode in voor een OAuth2-toegangstoken met je clientgeheim
6. Gebruik het OAuth2-toegangstoken in alle API-aanvragen met Authorization: Bearer YOUR_TOKEN

Het resultaat is dezelfde indeling voor OAuth2-toegangstokens als bij de methode Credentials Direct Token Exchange, wat zorgt voor consistente authenticatie bij beide aanpakken.

Raadpleeg de documentatie over OAuth2-authenticatie voor gedetailleerde richtlijnen voor de implementatie van OAuth2, inclusief codevoorbeelden en beveiligingsoverwegingen.

Problemen met authenticatie oplossen en best practices

Veelvoorkomende authenticatiefouten

401 Unauthorized

• Oorzaak: Ongeldig of ontbrekend toegangstoken
• Oplossing: Controleer of je token correct is en is opgenomen in de Authorization-header

403 Forbidden

• Oorzaak: Geldig token, maar onvoldoende rechten voor de aangevraagde actie
• Oplossing: Controleer of je gebruikersaccount de benodigde rechten voor de site heeft

Ongeldige tokenindeling

• Oorzaak: Onjuiste headerindeling
• Oplossing: Zorg dat je Authorization: Bearer YOUR_TOKEN gebruikt (let op de spatie na “Bearer”)

Best practices voor beveiliging

1. Stel nooit inloggegevens bloot in client-side code – Applicatiewachtwoorden mogen alleen worden gebruikt in server-side applicaties
2. Gebruik omgevingsvariabelen – Sla gebruikersnamen en wachtwoorden op in omgevingsvariabelen, niet in je broncode
3. Roteer wachtwoorden regelmatig – Genereer periodiek nieuwe applicatiewachtwoorden en trek oude in
4. Gebruik OAuth2 voor gebruikersgerichte apps – Gebruik geen applicatiewachtwoorden voor applicaties waarmee andere gebruikers zich authenticeren
5. Begrijp het uniforme tokensysteem – Beide authenticatiemethoden resulteren in dezelfde OAuth2-toegangstokens, wat consistente API-toegang en beveiliging biedt
6. Kies de juiste methode – Gebruik de snelkoppeling voor applicatiewachtwoorden voor persoonlijk/ontwikkelingsgebruik en de volledige OAuth2-flow voor applicaties van derden
7. Tokenbeheer – Tokens kunnen per applicatie worden ingetrokken zonder andere apps te beïnvloeden, wat betere beveiliging biedt dan het delen van wachtwoorden

Browsergebaseerde applicaties

Als je een browsergebaseerde applicatie bouwt, moet je het volgende doen:

1. Gebruik OAuth2 implicit flow – Applicatiewachtwoorden mogen niet worden gebruikt in client-side code
2. Zet je domeinen op de whitelist – Configureer toegestane origins in je WordPress.com-appinstellingen
3. Verwerk CORS correct – De API stuurt de juiste CORS-headers voor domeinen op de whitelist

Voor gedetailleerde richtlijnen over browsergebaseerde implementaties, zie De REST API gebruiken vanuit JS en de browser.

Resources en documentatie

• API-console – Interactief testen en verkennen
• API-referentie – Uitgebreide documentatie voor endpoints
• WordPress REST API-handboek – Officiële WordPress core REST API-documentatie
• Ontwikkelaarsblog – Updates en aankondigingen over API-wijzigingen