WordPress REST-API
De WordPress REST-API is bedoeld voor taal-onafhankelijke interactie over HTTP tussen een site en een computer. Vermoedelijk is REST-API completer en actueler dan de WP-CLI, omdat deze laatste soms gebaseerd is op deze eerste [1]
Voordelen REST-API
- Vermoedelijk completer & actueler dan WP-CLI
- Taal-onafhankelijk. Ik kan het dus ook gebruiken vanuit Python
- Compleet? Ik hoop dat de REST-API alle functionaliteit van een WordPress-site dekt, zodat ik alles via één interface kan regelen. Dit is overigens nog maar de vraag: Kan ik de taal van objecten instellen tijdens import?
Nadelen REST-API
- Weer een nieuwe techniek om te leren
- Ik betwijfel of ik zit te wachten om JSON te leren
- Ik heb de indruk dat de documentatie tav. REST-API+Python beperkt is
- Onduidelijk hoe je data importeert die op het snijvlak van meerdere plugins ligt, zoals de taal van producten tijdens import
Voorbeelden
- Mobiele apps die data uitwisselen met een server (bv. een winkel-app). JSON is compacter dan XML, en dat speelt hierbij mogelijk een rol
- Data importeren in een site.
Hoe compleet is deze interface?
Ik vermoed dat per plugin een aanvullende REST-API gedefineerd moet worden. Het ligt niet voor de hand dat alle plugin-ontwikkelaars dat doen. Noch dat die compleet is, noch dat je die zonder bijbetalen mag gebruiken. Voorbeeld: Polylang heeft een REST-API gedefineerd, maar alleen als je ervoor betaalt.
REST
[2]:
REST is an architectural style that helps create and organize a distributed system. It describes the web as a distributed hypermedia application whose linked resources communicate by exchanging representations of resource state.
Resources are the main building blocks of the REST architecture. In fact, they are the main building blocks of the web itself to the extent that the web is sometimes referred to as “resource-oriented”.
When talking about WordPress, these resources are discrete entities like posts, pages, comments, users, and custom post types etc. To interact with resources, URIs (Uniform Resource Identifier) are used, and as the name suggests, it’s an identifier for a resource.
A RESTful service treats URIs as the primary way to address an underlying resource. These resource may have several representations. For example, an image file might be available in .JPG, .GIF, or .PNG formats. The relationship between resources and URIs is one-to-many. A URI can only point to one specific resource but a resource may have more than one URIs.
Some resources currently supported by the WP REST API:
- Posts
- Pages
- Media
- Custom Post Types
- Post Meta
- Revisions
- Comments
- Terms
- Users
We can perform different actions on these resources using HTTP verbs.
Verbs
[3]:
The REST API offers several HTTP requests, known as HTTP verbs or verbs, the first four of which are CRUD actions (create, read, update & delete). The last two verbs assist a client in determining whether a resource exists and what HTTP verbs are available for it to perform further operations. This makes the RESTful service a self-documenting system:
GET:
Read or retrieve a resource (cRud). A GET request is idempotent i.e. a client can call it many times but it will not affect the state of a resource.POST:
Create a new resource (Crud)PUT:
Update a resource (crUd)DELETE:
Delete a resource (cruD)HEAD:
Check if a resource exists without returning its representationOPTIONS:
Retrieve all the verbs supported by a resource
Some examples: Retrieve the collection of all post entities:
GET wp/v2/posts
Retrieve the post with id=100:
GET wp/v2/posts/100
Create a new post:
POST wp/v2/posts
Update the post with id=100:
PUT wp/v2/posts/100
Routes & endpoints
- Routes are the paths to resources
- Endpoints are combinations of verbs and routes
E.g.:
GET wp/v2/posts
GET
is the verbwp/v2/posts
is the routeGET wp/v2/posts
is the endpoint
HTTP Response Status Codes
Als een server antwoord geeft, gaat dat vergezeld van een response code:
200 - OK
201 - Created
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
405 - Method not Allowed
410 - Gone
500 - Internal Server Error
501 - Not implemented
HTTP-clients
Als je met REST aan de slag gaat, heb je een HTTP-client nodig om te communiceren met (in dit geval) een WordPress-site. Bv.:
JSON Viewer (Chrom)
Superhandig. Altijd doen!
Requests (Python)
Dit is de bibliotheek die ik standaard gebruik op Python:
- Requests is een Python-library
- Ik bleek deze al te hebben gebruikt voor eerdere tests - Werkt super.
Postman (Google Chrome)
- Postman voor Chrome. Deze bleek depreciated te zijn. Ik belande op een algemene download-pagina. Misschien zoiets als Firebug vroeger voor Firefox. Installatie vind ik op dit moment te veel werk
- Toch wil ik zoiets op een dag hebben: Alleen via Python, is iets te indirect. Alsof dit de real-time command-line variant is.
Overig
Enable permalinks
Om consistente routes te hebben, is het belangrijk dat pretty permalinks zijn eabled in de betreffende WordPress-site. No worries: Het moet heel vreemd lopen, wil dat niet het geval zijn.
Simpele tests & voorbeelden
Bekijk alle routes & endpoints - Browser
Voeg /wp-json
achter de URL van een WordPress-site, en je ziet alle routes & endpoints. Met behulp van de Chrome JSON Viewer, is het ook nog leesbaar. Voorbeeld: https://stapelbakken.nl/wp-json. Dit zijn 36.000 regels! De eerste paar regels:
// 20190408161835 // https://stapelbakken.nl/wp-json { "name": "Stapelbakken.nl", "description": "Snel en gemakkelijk Haceka Stapelbakken bestellen", "url": "https://stapelbakken.nl", "home": "https://stapelbakken.nl", "gmt_offset": "0", "timezone_string": "", "namespaces": [ "oembed/1.0", "contact-form-7/v1", "wc/v1", "wc/v2", "wc/v3", "wordfence/v1", "wp/v2" ],
Bekijk alle routes & endpoints - Python
#! /usr/bin/python3 r = requests.get('http://rt_tmp.dvb/wp-json') print(r.status_code) # Output: 200 print(r.text) # Output: Als hierboven, maar zonder opmaak
Niet-bestaande route
#! /usr/bin/python3 r = requests.get('http://rt_tmp.dvb/wp-json/blub') print(r.status_code) print(r.text)
Output - Command line:
404 {"code":"rest_no_route","message":"Geen route gevonden die overeenkomt met de URL en aanvraagmethode","data":{"status":404}}
Output - Chrome met JSON-viewer:
Zomaar een geldige route
Ergens in de output van get(get('http://rt_tmp.dvb/wp-json)
pikte ik dit pad eruit:
r = requests.get('http://rt_tmp.dvb/wp-json/wp/v2') print(r.status_code) print(r.text)
Helaas nog steeds 5.480 regels, maar het idee van discovery en self-documentating spreekt me erg goed.
Overigens: wp
heeft hier betrekking op de WordPress Core-REST-API. Je kunt bv. ook de WooCommerce REST-API benaderen (versie 3, om precies te zijn):
r = requests.get('http://rt_tmp.dvb/wp-json/wp/v3')
Da's 10.813 regels - Meer dan WP zelf!
Authenticatie
Voor sommige requests is authenticatie vereist. Anders krijg je een 401-foutmelding. Authenticatie kan op verschillende manieren.
Basic authenticatie
Bij basic authenticatie, gaat een request gepaard met een base64-gecodeerde string username:password
. Dit is een onveilige manier van authenticeren, omdat base64-strings gemakkelijk te ontcijferen zijn.
Hoe specificeer je de taal bij product-import?
Het gaat om de combinatie van WooCommerce & Polylang
Ideeën
- Info bestaande producten opvragen. Dan kom ik vanzelf een taal-veld tegen, lijkt me
Namespaces?
De output van http://rt_tmp.dvb/wp-json
geeft al snel de namespaces aan:
"oembed/1.0", "wc/v1", "wc/v2", "wc/v3", "wordfence/v1", "yoast/v1", "wp/v2"
Dus hierbinnen moet het ergens zitten. Als ik zoek op lang, levert dat niets op.
Polylang REST-API
[4]:
- Er is een REST-API, maar je moet er wel voor betalen
- Hij defineert geen aparte namespace, maar is onderdeel van de
wp
-namespace (althans, in het voorbeeld op deze pagina)
Extending the REST-API
Zie ook
Bronnen
- https://codex.wordpress.org/WordPress_APIs - All WordPress API's
- https://www.youtube.com/watch?v=7YcW25PHnAA - REST API concept and examples
- https://developer.wordpress.org/rest-api/
- https://woocommerce.github.io/woocommerce-rest-api-docs/#create-a-product - REST-API in actie!
- https://www.hostinger.com/tutorials/wordpress-rest-api
Introductie & overzicht
Reference
Tutorial Tutsplus
Oogt compleet, maar is uit jan. 2016. Dit is op dit moment (april 2019) mijn belangrijkste bron.
- https://code.tutsplus.com/series/introducing-the-wp-rest-api--cms-896
- https://code.tutsplus.com/tutorials/introducing-the-wp-rest-api--cms-24533
Voorbeelden
- http://dominykasgel.com/woocommerce-rest-api-import-products-json/ - Vanuit PHP
- https://discussion.dreamhost.com/t/how-to-post-content-to-wordpress-using-python-and-rest-api/65166 - Vermoedelijk met Python 2 :(
- https://blogs.pjjk.net/phil/using-the-wordpress-rest-api-to-post-a-book-from-wikisource-to-pressbooks-with-python/
Requests (Python-bibliotheek)
Polylang & REST-API
- https://polylang.pro/doc/rest-api/
- https://wordpress.org/support/topic/how-to-know-the-language-of-a-post-through-the-wordpress-rest-api/
Authenticatie
- https://github.com/derwentx/wp-api-python
- https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/ - Onbegrijpelijk
- https://wordpress.org/support/topic/using-rest-api-with-python3-no-update-being-made/
- http://intelligentonlinetools.com/blog/2016/12/31/retrieving-post-data-using-the-wordpress-api-with-python-script/ - 2016???
- https://wp-oauth.com/docs/how-to/how-to-authenticate-with-wp-rest-api/ - 2019