WP REST API gegevens ophalen

In de vorige delen van de serie hebben we gekeken naar wat de WP REST API is en hoe deze ons kan helpen betere applicaties te maken met behulp van de WordPress-backend. 

Vervolgens hebben we gekeken naar twee manieren om verificatie op de server in te stellen voor het genereren van geverifieerde aanvragen. De eerste is de basisverificatiemethode, die handig is in ontwikkelomgevingen en snelle prototyping mogelijk maakt omdat het niet veel tijd kost om op te zetten. De tweede verificatiemethode is OAuth 1.0a, die wordt aanbevolen voor productieomgevingen omdat deze veel veiliger is dan de standaardverificatiemethode.

Nu we hebben geleerd hoe we authenticatie kunnen instellen, zijn we klaar om geverifieerde aanvragen te genereren om de volledige kracht van de WP REST API te ontketenen. We gebruiken basisverificatie in deze serie vanwege het gebruiksgemak, maar het wordt aanbevolen dat u OAuth 1.0a-verificatie gebruikt, zoals geleverd door de OAuth 1.0a-plug-in, voor uw productieservers.

In het huidige deel van de serie zullen we onze allereerste praktijkervaring opdoen met de WP REST API-plug-in. Wij zullen:

• analyseer de structuur van een KRIJGEN verzoek
• bekijk hoe het OPTIES vraag zelfdocumentatie aan van de API
• verzend verzoeken naar de server voor het ophalen van gegevens
• het serverantwoord analyseren dat eigenschappen, schema's en koppelingen bevat

Dus laten we beginnen met het analyseren van de structuur van een simpele KRIJGEN verzoek.

Anatomie van een KRIJGEN Verzoek

Voordat we ingaan op de details van het ophalen van gegevens met de WP REST API, moeten we ons vertrouwd maken met de syntaxis van een verzoek dat naar de server wordt verzonden. Dit zal een solide basis leggen voor onze toekomstige interacties met de WP REST API.

Beschouw de volgende aanvraag verzonden naar de server:

$ HULP http: // localserver / wp-json / wp / v2 / posts

Het type verzoek dat we verzenden, is KRIJGEN-een van de zes HTTP-werkwoorden die we in het eerste deel van deze serie hebben bekeken. EEN KRIJGEN aanvraag wordt gebruikt om gegevens van de server op te halen. Vandaar dat, wanneer het op de server wordt uitgevoerd, het bovenstaande verzoek een verzameling van alle postobjecten in de vorm van JSON-gegevens ophaalt.

Gezien de aanvraag URI, kunnen we deze in de volgende delen onderverdelen:

• http: // LocalServer /: De URL van mijn lokale ontwikkelingsserver. Het kan elke URL zijn, afhankelijk van waar uw WordPress-installatie zich bevindt.
• / Wp-json: Het is het eindpunt-voorvoegsel van de WP REST API.
• / wp: De naamruimte van de WP REST API-plug-in.
• / v2: Het is de versie van de WP REST API-plug-in.
• / berichten: Het is de bron die we van de server willen ophalen.

De naamruimte verhindert het overschrijven dat kan optreden bij het uitvoeren van meerdere plug-ins waarbij elk zijn eigen abstractielaag biedt voor de RESTful API. Vandaar dat elke abstractie op zijn eigen grens werkt zonder de methoden en eigenschappen die tot een andere abstractie behoren te beïnvloeden.

De naamruimte en versie waren niet aanwezig in de verouderde versie 1.2 van de plug-in. Dus in de oude versie zou het bovenstaande verzoek als volgt zijn:

$ HULP http: // localserver / wp-json / posts

Maar we zullen hier niet praten over compatibiliteit met eerdere versies. Als u meer wilt weten over alle wijzigingen die zijn opgetreden tussen versie 1.x en 2.x, kunt u deze vinden op de officiële pagina.

Naast het ophalen van een verzameling bronnen (berichten) met behulp van de bovenstaande URI, kunnen we ook een specifieke bron ophalen door de ID te vermelden:

$ GET / wp / v2 / posts / 100

De bovenstaande aanvraag retourneert een post-object als het neerkijkt op een post-resource met een ID van 100.

Andere keren moeten we ook zoeken naar berichten die aan een aantal specifieke criteria voldoen. Voor dat doel biedt de WP REST API een manier om de filter[] syntaxis:

$ GET / wp / v2 / posts? Filter [cat] = 1

Door het bovenstaande verzoek te verzenden, kunnen we alle berichten ophalen die behoren tot een categorie ID 1. De filtersyntaxis kan bijzonder nuttig zijn bij het opvragen van berichten of het navigeren tussen verschillende bronnen, bijvoorbeeld berichten en categorieën, met behulp van hun relaties.

Ten slotte, wanneer het gaat om argumenten die arrays als invoer gebruiken filter[] syntaxis kunnen we een lege set vierkante haken toevoegen om arrays als volgt uit te drukken:

$ GET / wp / v2 / posts? Filter [categorie__and] [] = 1 & filter [categorie__and] [] = 2

De bovenstaande syntaxis is gelijk aan de volgende WP_Query ():

 array (1, 2)));

Vandaar het bovenstaande KRIJGEN aanvraag haalt een lijst met berichten op die tot beide categorieën behoren met een ID van 1 en 2. Dezelfde syntaxis kan ook worden gebruikt voor matrixargumenten met meer dan twee elementen. Let op: het gebruik van de category__and parameter vereist gebruikersauthenticatie met edit_posts privileges.

We zullen kijken naar de filter[] syntaxis in meer detail in een later gedeelte.

Nu we hebben geleerd over het formatteren van een KRIJGEN verzoek en het verstrekken van zijn parameters, is het tijd om een ​​kijkje te nemen op de OPTIES verzoek. Een OPTIES aanvraag maakt het gemakkelijk om door de API te navigeren en dient feitelijk als een zelfdocumenterende manier om de API toegankelijker te maken door alle beschikbare HTTP-methoden op een eindpunt te documenteren, en op zijn beurt de argumenten die ze ondersteunen.

Navigeren door de API met behulp van de OPTIES Verzoek

Zoals eerder vermeld, de OPTIES verzoek kan zeer nuttig zijn bij het verkennen van de API. Het vermeldt alle eindpunten die bij een bepaalde route horen en biedt een lijst met parameters die door deze eindpunten worden ondersteund voor CRUD-bewerkingen.

Laten we een sturen OPTIES verzoek aan de / Wp / v2 / berichten route om te controleren welke endpoints het ondersteunt en welke parameters we langs de KRIJGEN verzoek om gegevens op te vragen:

$ curl -X OPTIES wp / v2 / berichten

Ik heb cURL gebruikt om het bovenstaande verzoek te verzenden, maar u kunt elk hulpmiddel van uw keuze gebruiken, inclusief Postman. Zorg ervoor dat u het volledige pad naar de bovenstaande route opneemt, inclusief het pad van uw server.

"namespace": "wp / v2", "methods": [...], "endpoints": [...], "schema": ..., "_links": ...

Bovenstaande OPTIES verzoek aan de / Wp / v2 / berichten route retourneert gegevens in de JSON-indeling die vijf eigenschappen bevat:

1. namespace
2. methoden
   
3. eindpunten
4. schema
   
5. _links
   

"namespace": "wp / v2", ...

De namespace eigenschap identificeert de naamruimte van de huidige plug-in. In ons geval is dat zo wp / v2, betekenende versie 2 van de WP REST API. We hebben al gekeken naar de naamruimte en het doel ervan in het vorige gedeelte.

... "methoden": ["GET", "POST"], ...

De methoden property bevat een array van alle methoden die door de huidige route worden ondersteund. Door naar het antwoord te kijken dat het bovenstaande verzoek heeft beantwoord, is het duidelijk dat het / Wp / v2 / berichten route ondersteunt twee methoden, namelijk KRIJGEN en POST. Het betekent dat we de kunnen gebruiken / Wp / v2 / berichten route om berichten op te halen, en om een ​​nieuw bericht te maken. We zullen omgaan met de POST methode in het volgende deel van deze serie, dus laten we ons concentreren op de KRIJGEN methode voorlopig.

De volgende eigenschap-eindpunten-bevat een array met de ondersteunde eindpunten voor de huidige route. Deze eigenschap is direct gekoppeld aan de eerder genoemde methoden eigenschap omdat deze eindpunten bevat voor de ondersteunde methoden.

... "eindpunten": ["methods": ["GET"], "args": ..., "methods": ["POST"], "args": ...], ...

De eindpunten eigenschap bevat objectwaarden die op hun beurt twee eigenschappen bevatten, namelijk methoden en args. De methoden eigenschap bevat een reeks HTTP-methoden en de volgende args eigenschap bevat alle ondersteunde argumenten voor deze methoden. Dit zijn de argumenten die we samen met de aanvraag verzenden in de vorm van URI-parameters.

Kijkend naar de argumenten ondersteund door de KRIJGEN methode, komen we negen argumenten tegen die omvatten context, pagina, per pagina, enz. Deze argumentobjecten bevatten twee eigenschappen, verplicht en standaard. De verplicht eigenschap geeft aan of het argument vereist is en de standaard eigenschap vertegenwoordigt de standaardwaarde van het argument.

"methods": ["GET"], "args": "context": "required": false, "default": "view", "page": "required": false, "default": 1, "per_page": "vereist": false, "default": 10, "filter": "vereist": false

De schema eigenschap in de geretourneerde antwoorddocumenten alle eigenschappen voor de huidige resource. Het schema definieert een structuur voor gegevens in de JSON-indeling. De schema-indeling die wordt gebruikt in de WP REST API is gebaseerd op concept 4 van de JSON-schemaspecificaties.

De laatste _links eigenschap bevat een array van objecten die de koppelingen van bijbehorende bronnen bevatten. De sleutel in het object geeft het relatietype (bijv. schrijver, verzameling, zelf, opmerkingen, enz.), met zijn waarde als de link naar die bijbehorende bron. Deze koppelingsstandaard is gebaseerd op HAL (Hypertext Application Language). U kunt meer informatie over HAL vinden door de specificaties te lezen die zijn geschreven door Mike Kelley.

Op een vergelijkbare manier kunnen we een OPTIES verzoeken om andere routes, inclusief die van gebruikers, opmerkingen, media, pagina's, enz., om hun ondersteunde methoden en argumenten te controleren. OPTIES verzoeken zijn uw beste vriend bij het werken met de WP REST API.

De WP REST API biedt nog een andere manier om de beschikbaarheid van de API te beoordelen door een KRIJGEN verzoek aan de / Wp-json index route. Hiermee worden alle routes en hun eindpunten samen met hun ondersteunde methoden en argumenten weergegeven.

$ curl -X KRIJG http: // wordpress-server / wp-json

De bovenstaande aanvraag retourneert een antwoordobject met de eigenschap routes als volgt:

Deze functie is enorm krachtig omdat alle routes en hun ondersteunde methoden en argumenten worden vermeld, waardoor het niet nodig is dat al deze externe gegevens worden gedocumenteerd. We zullen dit antwoordobject raadplegen bij het uitvoeren van CRUD-bewerkingen op verschillende bronnen.

Kijkend naar onze opties om de API te verkennen, gaan we nu aan de slag met de WP REST API om gegevens van de server op te halen.

Werken met berichten

Inmiddels hebben we ons vertrouwd gemaakt met de OPTIES aanvraag, wat een zelfdocumenterende manier is om de API-beschikbaarheid te beoordelen. We hebben ook gekeken naar hoe het ondersteunde methoden en argumenten voor een bepaalde route toont. Met behulp van deze kennis zijn we nu klaar om verschillende bronnen van de server op te halen met behulp van de WP REST API.

De bron waarmee we beginnen is de berichten bron, aangezien dit de belangrijkste bouwsteen is van WordPress. We zullen omgaan met het ophalen van berichten met behulp van verschillende filters. Als u deze kennis toepast, kunt u berichten opvragen met behulp van de WP REST API, net als met de klasse WP_Query ().

Gedurende deze reeks hebben we gewerkt met de berichten hulpmiddel om voorbeeldaanvragen en hun antwoorden te demonstreren, en we weten al hoe we postverzameling en een individuele post kunnen terugvinden door zijn ID. Dus we zullen dat niet nog een keer behandelen. In plaats daarvan bekijken we enkele meer geavanceerde manieren om berichten op te halen met behulp van de parameters op het hoogste niveau en de filter[] syntaxis.

Werken met topniveau-parameters

De WP REST API stelt enkele van de meest gebruikte queryvariabelen voor berichten direct op de KRIJGEN eindpunt. Deze parameters zijn:

1. context: De reikwijdte van het verzoek. Mogelijke waarden kunnen zijn uitzicht, embed of Bewerk.
2. pagina: De huidige pagina van de berichtverzameling.
3. per pagina: Totaal aantal berichten per pagina.
4. zoeken: De zoekopdracht. Beperk resultaten tot de overeenkomende reeks.
5. schrijver: De auteurs-ID. Wordt gebruikt om resultaten van een specifieke auteur te beperken.
6. uitsluiten: Een reeks post-id's om uit te sluiten van zoekresultaten.
7. omvatten: Beperk de resultaten tot post-ID's die in deze array zijn opgegeven.
8. compenseren: Offset de zoekresultaten op opgegeven aantal.
9. bestellen: De volgorde van de verzameling. Kan het zijn ASC of desc.
10. orderby: Sorteerkenmerk van de verzameling. Mogelijke waarden kunnen zijn ID kaart, titel of naaktslak.
11. naaktslak: Beperk de resultaten tot een bericht met een specifieke slak.
12. staat: Wordt gebruikt om de verzameling van berichten met een bepaalde status te beperken.

De context parameter wordt gebruikt om berichten op te halen, afhankelijk van de scope waarin we werken. Als we alleen een lijst met posts op een indexpagina weergeven, zijn we goed om met de uitzicht context. Maar als we berichten ophalen om ze te bewerken, dan moeten we de Bewerk context:

$ GET / wp / v2 / posts? Context = bewerken

De Bewerk contextparameter introduceert een extra rauw veld in velden zoals titel, inhoud, uittreksel, etc. De waarde hiervan rauw veld kan worden geëchood in de editor voor het bewerken van de inhoud.

De ... gebruiken Bewerk context vereist dat u wordt geverifieerd als een gebruiker met edit_posts privileges.

Gebruik makend van embed als de waarde van de context parameter haalt de verzameling berichten op met een minimale subset van hun eigenschappen.

De andere hierboven genoemde parameters spreken voor zich en u kunt ermee spelen in uw HTTP-client.

Dit waren de basisparameters waarmee u berichten kunt opvragen op basis van bepaalde criteria. Om onze zoekmogelijkheden te verfijnen, biedt de WP REST API de filter[] syntaxis die een subset van de ondersteunt WP_Query () args.

De ... gebruiken filter[] Syntaxis

Naast het ophalen van een verzameling berichten met enkele basisparameters op het hoogste niveau, geeft de WP REST API een deel van de WP_Query () variabelen met behulp van de filter[] syntaxis. Door deze syntaxis te gebruiken, kunnen we berichten op dezelfde manier opvragen als bij het werken met de WP_Query () klasse.

Parameters voor paginering zijn de belangrijkste van alle filters, omdat ze op grote schaal worden gebruikt op de pagina's met de berichtvermelding. Met de pagineringparameters kunnen we een specifiek aantal berichten per pagina weergeven en navigeren naar een specifiek aantal pagina's met berichten.

Standaard een KRIJGEN request haalt een verzameling van 10 berichten per pagina op. Laten we eens kijken hoe we een kunnen indienen KRIJGEN verzoek om slechts vijf berichten per pagina op te halen:

$ GET / wp / v2 / posts? Filter [posts_per_page] = 5

Het bovenstaande verzoek gebruikt de posts_per_page variabele die u misschien kent als u hebt gewerkt WP_Query ().

De wisselbare parameter wordt gebruikt in combinatie met de posts_per_page parameter, en deze wordt gebruikt om naar een bepaald aantal pagina's te navigeren. Na vijf berichten per pagina te hebben opgehaald, zouden we het volgende verzoek doen om naar de tweede pagina te gaan:

$ GET / wp / v2 / posts? Filter [posts_per_page] = 5 & filter [paged] = 2

De posts_per_page en wisselbare filters kunnen uitermate handig zijn bij het bouwen van paginering op listingpagina's met behulp van de WP REST API. Deze twee parameters zijn gelijk aan de per pagina en pagina top-level parameters. Vandaar dat de volgende aanvraag hetzelfde werk doet als de bovenstaande:

$ GET / wp / v2 / posts? Per_page = 5 & page = 2

In aanvulling op de verzameling berichten wordt het bovenstaande verzoek teruggestuurd, de server retourneert ook een aantal headers met een antwoord dat nuttige informatie bevat, inclusief het totale aantal berichten en het aantal pagina's. Deze waarden zijn opgenomen in de X-WP-TotalPages en X-WP-Total antwoordheaders.

De X-WP-TotalPages en X-WP-Total responskoppen zijn erg handig bij het maken van paginering met de WP REST API, omdat ze het totale aantal pagina's en het totale aantal berichten weergeven.

Afgezien van pagineringfilters, is het andere belangrijkste gebruik van de filter[] syntaxis is om berichten op hun datums te kunnen opvragen. Voor dit doel, de filter[] syntaxis ondersteunt acht parameters, dezelfde als die van de WP_Query () klasse:

1. jaar: Het viercijferige jaar (bijvoorbeeld 2015 of 2016)
2. monthnum: Het nummer van de maand van 1 tot 12
3. m: Zescijferige jaarmaand (bijvoorbeeld 201601)
4. w: De week van het jaar van 0 tot 53
5. dag: De dag van de maand van 1 tot 31
6. uur: Het uur van de dag van 0 tot 23
7. minuut: De minuut van het uur van 0 tot 60
8. tweede: De seconde van de minuut van 0 tot 60

Dus als we op zoek zijn naar de gepubliceerde berichten op de datum 2015-10-15 (jjjj / mm / dd), kan dit worden bereikt met de volgende query:

$ GET / wp / v2 / posts? Filter [jaar] = 2015 & filter [maandnum] = 10 & filter [dag] = 15

Een vergelijkbare query kan worden voorbereid met behulp van de bovenstaande parameters als we onze zoekopdracht moeten verfijnen tot het exacte uur en de exacte minuut.

We hebben al in een vorige sectie van deze tutorial gezien hoe we berichten die behoren tot een specifieke categorie of meerdere categorieën kunnen ophalen met behulp van de filter [cat] en filter [category__and] parameters. Nu zullen we de gebruiken filter [category__in] parameter om berichten weer te geven die behoren tot categorieën met een id van 5 en 6:

$ GET / wp / v2 / posts? Filter [categorie__in] [] = 5 & filter [categorie__in] [] = 6

De bovenstaande aanvraag haalt een lijst op van alle berichten die behoren tot categorieën met een id van 5 en 6.

Het tegenovergestelde effect kan worden bereikt door de filter [category__not_in] parameter op de volgende manier:

$ GET / wp / v2 / posts? Filter [category__not_in] [] = 5 & filter [category__not_in] [] = 6

Hiermee wordt een lijst met berichten opgehaald, met uitzondering van alle berichten die behoren tot categorieën met een ID van 5 of 6.

Er kan meer worden geschreven over het gebruik van de filter[] syntaxis, maar ik zal hier niet alles over hebben. U kunt een lijst met alle queryvariabelen vinden die worden ondersteund door de filter[] syntaxis in de officiële documentatie van versie 1 van de plug-in. Een groot deel van deze informatie is nog steeds geldig met versie 2 van de WP REST API, maar in sommige gebieden ontbreekt het nog steeds. Op het moment dat deze zelfstudie werd geschreven, bevat de officiële documentatie van versie 2 niets over de filter[] syntaxis en de query vars die het ondersteunt, maar we hopen in de nabije toekomst verbeteringen in de officiële documentatie te zien omdat er een aantal mensen (waaronder ikzelf) zijn die bijdragen aan de ontwikkeling en documentatie van de plug-in.

Nu we naar verschillende opties hebben gekeken bij het opvragen van berichten met behulp van de WP REST API, zijn we klaar om onze reis verder te gaan en te kijken naar enkele andere bronnen die worden ondersteund door de WP REST API.

Werken met nabewerkingen, categorieën, tags en meta

Met postrevisies kunt u bewerkingen in een bericht bekijken en herstellen. De API WP REST biedt een manier om alle revisies van een bericht te bekijken door de query uit te voeren / Berichten // herzieningen eindpunt. Vandaar dat voor een gegeven bericht met een ID van 10 alle revisies kunnen worden opgehaald door het volgende verzoek te verzenden:

$ GET / wp / v2 / posts / 10 / revisions

De bovenstaande aanvraag retourneert een array met revisievoorwerpen. Het revisies-object bevat een subset van eigenschappen die in het post-object zijn gevonden. Hieronder ziet u een voorbeeldrevisieobject in Postman:

Er kan een specifieke revisie worden opgehaald, aangezien we de id kennen. Dus een herziening met een ID van 2 met een bericht met een ID van 10 kan worden opgehaald door het volgende object:

$ GET / wp / v2 / posts / 10 / revisions / 2

De bovenstaande aanvraag retourneert één revisieobject.

Anders dan na herzieningen, kunnen categorieën voor een specifieke post worden opgevraagd door de volgende aanvraag:

$ GET / wp / v2 / categories? Post =

En voor de tags gebruiken we de volgende aanvraag:

$ GET / wp / v2 / tags? Post =

Met  de ID van de post zijn.

Als we post-meta moeten ophalen voor post met een ID van 10, sturen we de volgende aanvraag als een geverifieerde gebruiker:

$ GET / wp / v2 / posts / 10 / meta

Dit levert een reeks meta-objecten op.

Houd er rekening mee dat als u wilt werken met post- en pagina-meta in de WP REST API, u de bijbehorende plug-in moet hebben op GitHub door het WP REST API-team..

Werken met andere bronnen

Inmiddels hebben we een behoorlijk solide basis gekregen voor het werken met de WP REST API om gegevens op te halen. We hebben al gekeken naar het optiesverzoek en hoe het ons helpt de API te verkennen zonder de noodzaak voor externe documentatie. 

U kunt altijd een OPTIES aanvraag voor een bepaalde hulpbron en controleer welke eindpunten en parameters deze ondersteunt. Als u alle routes wilt weergeven die de WP REST API biedt, kunt u een KRIJGEN verzoek om het index-eindpunt op / Wp-json zoals we geleerd hebben aan het begin van deze tutorial.

Gezien dit voordeel van zelfdocumentatie, denk ik niet dat we verder elke afzonderlijke resource in deze tutorial moeten verkennen, omdat je dat nu zelf kunt doen.

What's Up Next?

In deze lange tutorial leerden we de API te verkennen met behulp van het OPTIONS-verzoek en ook gegevens ophalen van de server met behulp van de WP REST API. We hebben zojuist naar een handvol bronnen gekeken, waaronder posts, post-revisie en post-meta, omdat we niet alle ondersteunde bronnen in slechts één zelfstudie konden gebruiken. Maar nu zou u de API zelf moeten kunnen verkennen met behulp van de technieken die we in deze zelfstudie hebben geleerd.

WordPress heeft een ongelooflijk actieve economie. Er zijn thema's, plug-ins, bibliotheken en vele andere producten die u helpen uw site en project uit te bouwen. De open source aard van het platform maakt het ook een geweldige optie van waaruit je je programmeervaardigheden kunt verbeteren. Hoe het ook zij, u kunt zien wat we allemaal beschikbaar hebben op de Envato Marketplace.

In de volgende aflevering van deze serie zullen we leren om de andere drie bewerkingen van CRUD uit te voeren, d.w.z. bronnen te maken, bij te werken en te verwijderen. Blijf dus op de hoogte ...