WordPress REST-API: verschil tussen versies

Uit De Vliegende Brigade
Naar navigatie springen Naar zoeken springen
 
(44 tussenliggende versies door dezelfde gebruiker niet weergegeven)
Regel 13: Regel 13:
 
* Ik heb de indruk dat de documentatie tav. REST-API+Python beperkt is
 
* 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
 
* 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 [https://polylang.pro/doc/rest-api/ als je ervoor betaalt].
  
 
== REST ==
 
== REST ==
Regel 74: Regel 83:
 
* ''Endpoints'' are combinations of ''verbs'' and ''routes''
 
* ''Endpoints'' are combinations of ''verbs'' and ''routes''
  
−
E.g., in
+
E.g.:
  
 
  GET wp/v2/posts
 
  GET wp/v2/posts
  
−
* <code>GET</code> is the verb
+
* <code>GET</code> is the ''verb''
 
* <code>wp/v2/posts</code> is the route
 
* <code>wp/v2/posts</code> is the route
 
* <code>GET wp/v2/posts</code> is the ''endpoint''
 
* <code>GET wp/v2/posts</code> is the ''endpoint''
  
−
Ander voorbeeld: Voeg <code>/wp-json</code> achter de URL van een WordPress-site, en je ziet alle ''routes & endpoints''. Met behulp van de [https://chrome.google.com/webstore/detail/json-viewer/gbmdgpbipfallnflgajpaliibnhdgobh Chrome JSON Viewer], is het ook nog leesbaar. Voorbeeld: https://stapelbakken.nl/wp-json. Dit zijn 36.000 regels! De eerste paar regels:
+
== HTTP Response Status Codes ==
 +
 
 +
Als een server antwoord geeft, gaat dat vergezeld van een ''response code'':
 +
 
 +
* <code>200 - OK</code>
 +
* <code>201 - Created</code>
 +
* <code>400 - Bad Request</code>
 +
* <code>401 - Unauthorized</code>
 +
* <code>403 - Forbidden</code>
 +
* <code>404 - Not Found</code>
 +
* <code>405 - Method not Allowed</code>
 +
* <code>410 - Gone</code>
 +
* <code>500 - Internal Server Error</code>
 +
* <code>501 - Not implemented</code>
 +
 
 +
== 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:
 +
 
 +
* [http://docs.python-requests.org/en/latest/ Requests] is een Python-library
 +
* Ik bleek deze al te hebben gebruikt voor eerdere tests - Werkt super.
 +
 
 +
=== Postman (Google Chrome) ===
 +
 
 +
* [https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en 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 [https://learning.getpostman.com/docs/postman/launching_postman/installation_and_updates/ 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 ===
 +
 
 +
* [https://addons.mozilla.org/en-us/firefox/addon/rest-easy/ Rest Easy] voor Firefox
 +
* [https://github.com/jkbrzt/httpie httpie] voor de command-line
 +
 
 +
== 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 <code>/wp-json</code> achter de URL van een WordPress-site, en je ziet alle ''routes & endpoints''. Met behulp van de [https://chrome.google.com/webstore/detail/json-viewer/gbmdgpbipfallnflgajpaliibnhdgobh Chrome JSON Viewer], is het ook nog leesbaar. Voorbeeld: https://stapelbakken.nl/wp-json. Dit zijn 36.000 regels! De eerste paar regels:
  
 
<pre>
 
<pre>
Regel 105: Regel 162:
 
   ],
 
   ],
 
</pre>
 
</pre>
 +
 +
=== Bekijk alle routes & endpoints - Python ===
 +
 +
<pre>
 +
#! /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
 +
</pre>
 +
 +
=== Niet-bestaande route ===
 +
 +
<pre>
 +
#! /usr/bin/python3
 +
 +
r = requests.get('http://rt_tmp.dvb/wp-json/blub')
 +
print(r.status_code)
 +
print(r.text)
 +
</pre>
 +
 +
Output - Command line:
 +
 +
<pre>
 +
404
 +
 +
{"code":"rest_no_route","message":"Geen route gevonden die overeenkomt met de URL en aanvraagmethode","data":{"status":404}}
 +
</pre>
 +
 +
Output - Chrome met JSON-viewer:
 +
 +
{|
 +
|[[file:20190409-1415.png|thumb|Output van een get-request naar een niet-bestaande route. Als je het tussenvoegsel <code>wp-json</code> achterwege laat, wordt GET als een gewoon HTTP-request geïnterpreteerd]]
 +
|}
 +
 +
=== Zomaar een geldige route ===
 +
 +
Ergens in de output van <code>get(get('http://rt_tmp.dvb/wp-json)</code> pikte ik dit pad eruit:
 +
 +
<pre>
 +
r = requests.get('http://rt_tmp.dvb/wp-json/wp/v2')
 +
print(r.status_code)
 +
print(r.text)
 +
</pre>
 +
 +
Helaas nog steeds 5.480 regels, maar het idee van ''discovery'' en ''self-documentating'' spreekt me erg goed.
 +
 +
Overigens: <code>wp</code> 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 <code>username:password</code>. 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 <code>http://rt_tmp.dvb/wp-json</code> geeft al snel de ''namespaces'' aan:
 +
 +
<pre>
 +
  "oembed/1.0",
 +
  "wc/v1",
 +
  "wc/v2",
 +
  "wc/v3",
 +
  "wordfence/v1",
 +
  "yoast/v1",
 +
  "wp/v2"
 +
</pre>
 +
 +
Dus hierbinnen moet het ergens zitten. Als ik zoek op ''lang'', levert dat niets op.
 +
 +
== Polylang REST-API ==
 +
 +
[https://polylang.pro/doc/rest-api/]:
 +
 +
* Er is een REST-API, maar je moet er wel voor betalen
 +
* Hij defineert geen aparte ''namespace'', maar is onderdeel van de <code>wp</code>-namespace (althans, in het voorbeeld op deze pagina)
 +
 +
== Extending the REST-API ==
 +
 +
* https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/
  
 
== Zie ook ==
 
== Zie ook ==
Regel 110: Regel 262:
 
* [[Bulkimport (WordPress)]]
 
* [[Bulkimport (WordPress)]]
 
* [[WC-CLI (WordPress)]]
 
* [[WC-CLI (WordPress)]]
 +
* [[Db-bulk (WordPress)]]
  
 
== Bronnen ==
 
== Bronnen ==
Regel 118: Regel 271:
 
* https://woocommerce.github.io/woocommerce-rest-api-docs/#create-a-product - REST-API in actie!
 
* https://woocommerce.github.io/woocommerce-rest-api-docs/#create-a-product - REST-API in actie!
 
* https://www.hostinger.com/tutorials/wordpress-rest-api
 
* https://www.hostinger.com/tutorials/wordpress-rest-api
 +
 +
=== Introductie & overzicht ===
 +
 +
* https://www.codeinwp.com/blog/wordpress-rest-api/
 +
 +
=== Reference ===
 +
 +
* https://developer.wordpress.org/rest-api
 +
* https://developer.wordpress.org/rest-api/reference/
  
 
=== Tutorial Tutsplus ===
 
=== Tutorial Tutsplus ===
Regel 129: Regel 291:
  
 
* http://dominykasgel.com/woocommerce-rest-api-import-products-json/ - Vanuit PHP
 
* 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
+
* 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/
 
* https://blogs.pjjk.net/phil/using-the-wordpress-rest-api-to-post-a-book-from-wikisource-to-pressbooks-with-python/
 +
 +
=== Requests (Python-bibliotheek) ===
 +
 +
* http://docs.python-requests.org/en/latest/
 +
 +
=== 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

Huidige versie van 10 apr 2019 om 11:20

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"