De WordPress REST API – Volledige gids voor starters

De WordPress REST API gaat WordPress helemaal veranderen. Het is je wellicht nog niet opgevallen aangezien een groot deel van de veranderingen onder de motorkap plaatsvinden. Toch zijn we er zeker van dat de REST API een enorme impact heeft op de toekomst van WordPress, zowel voor de code zelf als de manier waarop de code wordt gebruikt.

Als je nog niet met de WordPress REST API hebt gewerkt of er überhaupt nog nooit van hebt gehoord, dan ben je misschien wel benieuwd waar alle heisa over gaat. Laten we dus eerst eens kijken naar wat de REST API precies is.

Wat is de WordPress REST API?

De WordPress REST API is een interface die ontwikkelaars kunnen gebruiken om toegang te krijgen tot WordPress vanaf buiten de normale WordPress-installatie. Je kunt toegang krijgen via JavaScript, waardoor je de API dus kan gebruiken om interactieve websites en apps te maken.

REST staat voor REpresentational State Transfer en API voor Application Programming Interface. Laten we eens kijken wat dat precies betekent.

Wat is een Application Programming Interface (API)?

Een Application Programming Interface, of API, wordt gedefinieerd als:

“Een interface of communicatie-protocol tussen een client en een server die als doel heeft om het bouwen van software aan de zijde van de client te vereenvoudigen.”

Als je niet bekend bent met API’s, zegt deze definitie misschien niet zoveel. Om het wat simpeler uit te drukken: een API een codeset die een systeem in staat stelt te interacteren (EN: ‘interface’) met een ander systeem. Als je bijvoorbeeld wel eens een kaart van Google hebt toegevoegd aan je WordPress-website, dan heb je de Google Maps API gebruikt, die ervoor zorgt dat je WordPress-website kan communiceren met Google Maps.

Deze systemen hoeven niet helemaal onafhankelijk zijn. Zo heeft WordPress al meerdere API’s, voor zaken zoals plugins, instellingen en shortcodes. Ontwikkelaars van plugins en thema’s kunnen deze API’s gebruiken om te communiceren met de WordPress-core om dingen te laten gebeuren (zoals het maken van shortcodes en toevoegen van instellingen aan de WordPress-admin omgeving).

Het verschil met de REST API is dat het ervoor zorgt dat systemen buiten je WordPress-installatie kunnen communiceren met WordPress, waar het ‘REST’-deel voor gebruikt wordt.

Wat is een REpresentational State Transfer (REST)?

Representational State Transfer, of REST, bepaalt een standaard waardoor websystemen met elkaar kunnen communiceren. Zonder REST zouden twee verschillende systemen elkaar niet kunnen begrijpen en dus geen data kunnen uitwisselen.

Als een applicatie RESTful wil zijn, moet deze voldoen aan vijf voorwaarden:

1. Uniforme interface. De URL’s die gebruikt worden om toegang te krijgen tot de resources van het systeem moeten uniform en consistent zijn en te bereiken via een gebruikelijke methode, zoals GET (daarover later meer).
2. Client-server. Client-applicaties en server-applicaties moeten onafhankelijk zijn, zodat ze ook onafhankelijk van elkaar ontwikkeld kunnen worden. Als de technologie aan de serverzijde (bijv. WordPress) verandert, moet de applicatie aan de serverzijde (bijv. een app) nog altijd toegang tot de resources kunnen krijgen via dezelfde eenvoudige methode.
3. Stateless. De server verandert niet van state wanneer een nieuw verzoek wordt gedaan via de API. Het slaat ook de verzoeken die gedaan zijn niet op.
4. Cachebaar. Alle resources moeten te cachen zijn, om de snelheid en overeenstemming met webstandaarden te verbeteren. Caching kan worden gedaan aan zowel de server- en clientzijde.
5. Gelaagd systeem. Een RESTful systeem biedt je meerdere lagen om toegang toe te krijgen, waarbij het indien nodig data opslaat op tussenliggende servers. De server weet dus niet of de eind-client een directe verbinding heeft of niet.

Al deze beperkingen gelden voor zowel webpagina’s als applicaties en bepalen de manier waarop een applicatie kan communiceren met de API.

Wat Betekent Dit Voor WordPress?

Het samenvoegen van REST en API betekent dat de WordPress REST API over een set code beschikt die het mogelijk maakt voor andere systemen om te communiceren met WordPress, en dat zodanig gebouwd is dat de verschillende systemen elkaar te allen tijde begrijpen.

Het betekent ook dat een website of mobiele app van een derde partij bijvoorbeeld bij je WordPress-database kan, er data van kan ophalen en data aan kan toevoegen.

Dit heeft natuurlijk een aantal gevolgen en er zijn verschillende manieren om hier gebruik van te maken.

De WordPress REST API Begrijpen

De WordPress REST API is ontwikkeld als antwoord op de veranderende manier waarop websites en apps worden ontwikkeld en met het oog op het breder toegankelijk maken van WordPress.

Achtergrond van de WordPress REST API

De WordPress REST API is uitgebracht als onderdeel van de nieuwe kern van versie 4.7 in december 2016, maar bestond eerder al als plugin.

Het is ontwikkeld om een brede selectie van WordPress-applicaties te kunnen ondersteunen en om WordPress te transformeren van een content management systeem naar een applicatie-platform.

Het wordt veel gebruikt door WordPress.com, waar de interface – die steunt op JavaScript – de REST API gebruikt om te communiceren met de WordPress-database. Het wordt ook gebruikt door de Gutenberg bewerkingsinterface die onderdeel werd van de WordPress-core in 2019.

De REST API vergroot het aantal applicaties dat WordPress kan gaan gebruiken. Alhoewel een content management systeem bijzonder goed is voor het beheren van een complexe website, kan een applicatie-platform ook gebruikt worden om web-based single-page applicaties of SPA’s te laten draaien (die heb je wel eens gebruikt als je ooit Google Docs hebt gebruikt).

Daarbij wordt de content ververst als de gebruiker een actie uitvoert, in plaats van dat een hele nieuwe pagina geladen wordt. Omdat het JavaScript (een client-zijde taal) gebruikt in plaats van PHP (een server-zijde taal), kan het dingen uitvoeren in de browser van de gebruiker zonder dat het constant nieuwe verzoeken naar de server hoeft te sturen.

Gevolgen Voor WordPress-gebruikers en -ontwikkelaars

Als je een gebruiker en/of ontwikkelaar bent van WordPress, dan heeft de REST API een aantal consequenties.

Voor gebruikers zijn de gevolgen bijvoorbeeld:

• Veranderingen aan de interface, inclusief de Gutenberg Editor.
• Veranderingen en verbeteringen aan de WordPress mobiele app.
• Zelf-gehoste WordPress admin-pagina’s zullen naar verloop van tijd steeds meer op de WordPress.com-schermen gaan lijken.

Voor ontwikkelaars zijn er meer gevolgen én meer mogelijkheden:

• De mogelijkheid om SPA’s te maken door middel van de REST API, waarbij je de data van WordPress af haalt maar het er toch heel anders dan WordPress uitziet.
• De mogelijkheid om WordPress te integreren met andere front-end technologieën en systemen.
• De mogelijkheid om met WordPress te ontwikkelen, zelfs als je een front-end ontwikkelaar bent die geen PHP schrijft.
• Voor PHP-ontwikkelaars, is er een steeds grotere noodzaak om ook JavaScript te gaan beheersen.
• Specifieke veranderingen zoals de noodzaak om Gutenberg-blokken te gaan bouwen in plaats van meta-boxen in de bewerkingsschermen bij pagina’s en artikelen.

Naar verloop van tijd zal de WordPress REST API als gevolg hebben dat steeds meer van de WordPress-core in JavaScript geschreven zal worden in plaats van PHP. Als je een WordPress-ontwikkelaars bent, zal dat dus betekenen dat je JavaScript moet gaan leren.

Toegang Krijgen tot de WordPress REST API

Hoe krijg je toegang tot de WordPress REST API?

Om toegang te krijgen tot de WP-REST API moet je verbinding maken met je website via de opdrachtregel, oftewel de command line. Bij WordPress heet dit WP-CLI. Je doet dit dus niet via je admin-schermen of door direct de code op je website te bewerken.

Laten we eens kijken hoe je ermee begint.

Toegang Krijgen tot de WP-REST via WP-CLI

WP-CLI is de WordPress Command Line Interface. Het biedt de mogelijkheid om toegang te krijgen tot WordPress en veranderingen door te voeren via de Command Line Interface (CLI) oftewel opdrachtprompt op je computer. WP-CLI is standaard geïnstalleerd bij alle hostingpakketten van Kinsta.

Om de CLI te openen, open je de Terminal op de Mac of Linux, of de opdrachtprompt in Windows.

Om verbinding te maken met een website op afstand, maak je via SSH verbinding met je server om WP-CLI-toegang te krijgen (Kan je geen verbinding maken via SSH? Leer hoe je de SSH-foutmelding “Connection Refused” kan oplossen.).

Om verbinding te maken met een lokale site, hoef je alleen maar het juiste bestandpad te gebruiken in de opdrachtregel. Het is een goed idee om eerst met de REST API te experimenteren op een lokale testwebsite voordat je het uitprobeert op een live website.

Je moet verbinding maken met de specifieke REST API voor jouw website, zo bijvoorbeeld:

http://yoursite.com/wp-json/wp/v2

Je kunt vervolgens elementen aan deze regel toevoegen om toegang te krijgen tot bepaalde datatypen. Hoe dit precies gaat, leggen we zo meteen uit. Deze elementen worden ook wel endpoints of eindpunten genoemd.

Authenticatie

Als je verbinding hebt gelegd met je website, moet je je wellicht nog authentiseren. Sommige endpoints zijn publiekelijk toegankelijk en hebben geen authenticatie nodig, anderen weer wel.

Authenticatie bij REST API werkt anders dan je normaal gesproken gewend bent: het is dus geen kwestie van inloggen op je website-admin.

Om je te identificeren op je website via de WP-CLI, moet je eerst een authenticatie-plugin installeren. Voor ontwikkelwebsites doet de Basic Auth plugin alles wat wordt gevraagd; de plugin is bovendien eenvoudig in gebruik.

Maar voor live websites zul je een meer robuuste vorm van authenticatie willen gebruiken, zoals de JWT Authentication plugin, die de JSON Web Token gebruikt en daardoor veiliger is.

Je kunt vervolgens de opdrachtregel gebruiken om bij je data te komen en de authenticatie af te ronden.

Het voorbeeld hieronder gebruikt curl om de verbinding met WordPress te testen. De output zal een lijst zijn met artikelen die momenteel als concept geregistreerd staan.

curl -X GET --user username:password -i http://yoursite.com/wp-json/wp/v2/posts?status=draft

Conceptartikelen zijn niet publiekelijk toegankelijk, dus je zult je moeten identificeren om toegang te krijgen. Dat betekent ook dat je geen authentiseren niet nodig is als de informatie die je opvraagt wel openbaar is. Om een aantal artikelen te krijgen die je al gepubliceerd hebt, zou je dus het volgende kunnen gebruiken:

curl -X GET http://yoursite.com/wp-json/wp/v2/posts

Met deze opdracht ontvang je alle artikelen die je gepubliceerd hebt, aangezien deze voor iedereen toegankelijk zijn.

Een Overzicht van de Commando’s voor de WordPress REST API

Als je toegang hebt tot je website en weet hoe je je moet identificeren (en of dit inderdaad nodig is), zul je verschillende commando’s moeten gebruiken om je website te bewerken.

De commando’s die je nodig hebt, zijn:

• GET haalt een resource op, zoals een artikel of andere data.
• POST voegt een resource toe aan de server, zoals een artikel, bijlage of iets anders.
• PUT kan worden gebruikt om een resource te bewerken die al op de server staat.
• DELETE verwijdert een resource van de server. Gebruik die voorzichtig!

Laten we deze allemaal bekijken.

GET

De GET-opdracht is waarschijnlijk de meest gebruikte: het haalt data op. Het voorbeeld hieronder (die je kan gebruiken zodra je met succes toegang hebt gekregen tot je site) haalt een lijst op met alle gepubliceerde pagina’s binnen je website:

GET http://yoursite.com/wp-json/wp/v2/posts/?status=published

Let op dat ik in bovenstaand voorbeeld niet het volledige adres van de website gebruikte, omdat ik al eerder via WP-CLI toegang had aangevraagd.

Nadat je deze data opgehaald hebt, kun je deze gebruiken om je volgende stap te plannen. Je wilt wellicht één van deze artikelen verwijderen, bewerken of updaten. Je zou ook eenvoudigweg de artikelen naar je web-app door kunnen zetten.

Laten we zeggen dat je het laatste (nieuwste) artikel wilt ophalen. Dan gebruik je dit:

POST http://yoursite.com/wp-json/wp/v2/posts/

Er zijn verschillende argumenten of parameters die je kunt gebruiken wanneer je werkt met artikelen. Zie het WordPress REST API Handbook voor meer details.

POST

Gebruik POST om nieuwe data of resources aan je website toe te voegen.

Stel dat je bijvoorbeeld een nieuw artikel wilt maken, dan begin je door de POST-opdracht te gebruiken:

POST /wp/v2/posts/

Dit zou een nieuw concept-artikel aanmaken.

Je kunt dan vervolgens het artikel bewerken door een PUT-opdracht te gebruiken.

Met een POST-opdracht kun je ook andere resources dan artikelen aan je website toevoegen, bijvoorbeeld bijlagen of andere artikel-typen.

Om een pagina toe te voegen aan je website, gebruik je bijvoorbeeld zoiets:

POST http://yoursite.com/wp-json/wp/v2/posts/pages

Dit maakt een lege pagina aan op dezelfde manier als je zojuist een nieuw artikel hebt aangemaakt.

PUT

De PUT-opdracht laat je een bestaande resource bewerken, inclusief artikelen.

Laten we zeggen dat je enkele conceptartikelen op je website hebt staan. Je wilt deze controleren, en er eentje updaten om te publiceren.

Dan begin je door eerst een lijst op te halen met alle concept-artikelen:

POST http://yoursite.com/wp-json/wp/v2/posts/?status="draft"

Je krijgt dan een lijst met alle huidige concept-artikelen. Je kunt de status van één van deze veranderen door het specifieke ID te gebruiken:

PUT http://yoursite.com/wp-json/wp/v2/posts/567

Hierdoor maak je verbinding met dat specifiek artikel waardoor je het kunt bewerken. Je kunt vervolgens de status veranderen via het status-argument:

{
"status" = "publish"
}

Je zou ook content kunnen toevoegen aan het artikel en dan pas publiceren:

{
"status" = "publish"
"content" = "content here"
}

De server antwoordt met een 200 - OK-status waardoor je weet dat het PUT-verzoek het artikel succesvol heeft aangepast.

DELETE

De DELETE-opdracht doet precies wat je ervan zou verwachten: het verwijdert een resource. Standaard wordt een verwijderd artikel eerst in de prullenbak geplaatst voordat het definitief verwijderd wordt.

Dus als je het artikel dat je net aangemaakt hebt wilt verplaatsen naar de prullenbak, gebruik je dit:

DELETE http://yoursite.com/wp-json/wp/v2/posts/567

Maar als je de prullenbak wilt omzeilen en het artikel meteen definitief wilt verwijderen, gebruik je het force-argument:

DELETE http://yoursite.com/wp-json/wp/v2/posts/567?force=true

Dit verwijdert het artikel definitief, zonder mogelijkheid om het ongedaan te maken, dus wees er voorzichtig mee.

Wanneer je de WordPress REST API Níet Moet Gebruiken

De WordPress REST API is niet altijd de juiste aanpak om een website of app te ontwikkelen. Enkele overwegingen voordat je het gaat gebruiken voor ontwikkeling:

Compatibiliteit

Als je app gebruikt gaat worden door apparaten die geen JavaScript kunnen gebruiken of gebruikers hebben die JavaScript waarschijnlijk uit hebben staan, dan werkt je app niet als je de REST API gebruikt.

Een WordPress-website die geprogrammeerd is in PHP zal HTML als output hebben, en dus dit probleem omzeilen. Apparaten die geen JavaScript gebruiken worden steeds zeldzamer, maar als je specifieke apps aan het ontwikkelen bent voor zo’n apparaat, zal de REST API niet werken.

Op dezelfde manier zal de REST API niet werken bij gebruikers die JavaScript uit hebben staan. Sommige gebruikers doen dit binnen hun browser vanwege toegankelijkheid of veiligheid.

Toegankelijkheid

Sites of apps die zijn ontwikkeld met JavaScript zijn soms iets minder toegankelijk dan website die output geven in HTML.

Dit is vooral omdat JavaScript wordt gebruikt om dynamische content af te leveren die niet goed samenwerkt met schermlezers, en dus problemen veroorzaakt voor mensen die slecht zien of lichtgevoelige epilepsie hebben.

Je kunt de REST API gebruiken om toegang te krijgen tot je WordPress-website en vervolgens de data opleveren in een format dat toegankelijker is, zodat je dit probleem omzeilt. Het is echter zeker de moeite waard om een oogje te houden op de toegankelijkheid van je website terwijl je dit aan het ontwikkelen bent.

SEO

Single Page Applications, die zichzelf vaak verversen, kunnen soms problemen met SEO veroorzaken. Dit komt doordat content niet direct geleverd wordt wanneer de pagina voor het eerst laadt, waardoor het niet wordt geïndexeerd door zoekmachines.

Google en andere zoekmachines doen hun best om dit probleem te verhelpen omdat veel websites tegenwoordig als SPA draaien. De afgelopen tijd is het indexeren van dit soort sites dus al sterk verbeterd. Toch is het zeker de moeite waard om een grondige SEO audit van je website te doen als je de REST API gebruikt.

Hoe Schakel je de WordPress REST API uit

Als je niet wilt dat applicaties toegang tot je data hebben via de REST API, dan kun je dit uitschakelen. Onthoud dat publieke data altijd toegankelijk is voor iedereen, niet alleen voor jou.

Om het uit te schakelen, kun je de Disable WP REST API plugin installeren. Dit schakelt de REST API uit voor iedereen die niet ingelogd is op je website.

Je kunt ook code toevoegen aan het functions-bestand van je thema of je eigen plugin schrijven. Het is meestal beter een plugin te schrijven omdat deze functionaliteit niet thema-specifiek is.

In je plugin voeg je slechts twee regels code toe:

add_filter( 'json_enabled', '__return_false' );
add_filter( 'json_jsonp_enabled', '__return_false' );

Dit schakelt de REST API volledig uit voor je website. Het kan wel neveneffecten hebben voor je admin-pagina’s dus check even of alles goed werkt nadat je het toegevoegd hebt.

Praktijkvoorbeelden van Apps die de WordPress REST API al Gebruiken

De REST API biedt spannende mogelijkheden voor de toekomst van WordPress. Hier zijn enkele voorbeelden van applicaties en sites die de WordPress REST API gebruiken om SPA’s te maken of die WordPress linken aan andere websites en technologieën.

WordPress.com

De WordPress.com admin-schermen zijn helemaal gebouwd door middel van de REST API om een SPA te maken waarmee gebruikers hun website kunnen beheren.

Hierdoor ontstaat er dynamische communicatie tussen de interface en server, waardoor er een gebruiksvriendelijke interface ontstaat die WordPress.org binnenkort zal gaan namaken.

De Block Editor (Gutenberg)

Niet alleen in de beheerderspagina’s van WordPress.com, maar nu ook in de zelf-gehoste WordPress websites gebruikt de Gutenberg Blockeditor de REST API om te communiceren met je database en om blokken te maken.

Om bepaalde post-types te laten werken met de Gutenberg-editor, moet de REST API ingeschakeld zijn. Dat betekent dat als je een custom post-type aanmaakt en Gutenberg gebruikt, je de volgende regel aan de blockeditor moet toevoegen voor dat specifieke type:

"show_in_rest" = true;

Event Espresso

Event Espresso is een WordPress-plugin waarmee gebruikers evenementen kunnen organiseren en publiceren. Het gebruikt de REST API zodat gebruikers bij de data kunnen van buiten WordPress. Dit betekent dat je ook mobiele apps of SPA’s kunt bouwen om je evenementen te beheren.

UsTwo

UsTwo is een digitaal bedrijf dat zijn site heeft gebouwd als Single Page Application door de REST API te gebruiken. De site combineert een front-end constructie door middel van React, met een back-end op basis van WordPress (voorgestelde lezing: Een gids voor het starten en runnen van een succesvol WordPress-bureau).

De content van hun single page is modulair, met een andere structuur dan de standaard WordPress-pagina. Om dit te laten werken, gebruiken ze een aangepaste page builder plugin die hun team de mogelijkheid geeft om modulaire content toe te voegen aan hun website.

USA Today

USA Today heeft hun website opnieuw gebouwd door middel van de WordPress REST API-integratie met de bestaande systemen en modules op hun website.

De REST API maakt het mogelijk dat de content doorgezet wordt naar andere outlets zoals Facebook Instant Articles en Apple News door middel van JSON. Ze hebben ook een online sociale game gemaakt voor hun sport-sectie, op basis van JavaScript.

Samenvatting

De WordPress REST API biedt enkele interessante uitdagingen, maar ook veelbelovende mogelijkheden voor zowel gebruikers als ontwikkelaars van WordPress. Het is de toekomst van WordPress en zal waarschijnlijk de manieren waarop we WordPress gebruiken en ontwikkelen radicaal veranderen.

Wat denk jij van de REST API? Heb je het al gebruikt voor een project? Laat het ons weten in de reacties hieronder!