WordPress REST-API

Uit De Vliegende Brigade
Naar navigatie springen Naar zoeken springen
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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:

  1. 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.
  2. POST: Create a new resource (Crud)
  3. PUT: Update a resource (crUd)
  4. DELETE: Delete a resource (cruD)
  5. HEAD: Check if a resource exists without returning its representation
  6. OPTIONS: 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 verb
  • wp/v2/posts is the route
  • GET 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:

Output van een get-request naar een niet-bestaande route. Als je het tussenvoegsel wp-json achterwege laat, wordt GET als een gewoon HTTP-request geïnterpreteerd

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

Introductie & overzicht

Reference

Tutorial Tutsplus

Oogt compleet, maar is uit jan. 2016. Dit is op dit moment (april 2019) mijn belangrijkste bron.

Voorbeelden

Requests (Python-bibliotheek)

Polylang & REST-API

Authenticatie

Overgenomen van "https://wiki.devliegendebrigade.nl/index.php?title=WordPress_REST-API&oldid=17124"