Fördjupad guide i att skapa och hämta anpassade WP REST API-slutpunkter
Det här inlägget kommer att visa hur man skapar anpassade WordPress REST-slutpunkter och olika metoder för att utföra förfrågningar till dem. Det kommer att finnas exempel i både PHP, jQuery och vanilla Javascript.
Jag antar att du redan är bekant med vad WP REST API är, men här är en kort sammanfattning. WordPress REST API är ett JSON-gränssnitt för att skicka och ta emot data från din WordPress-webbplats. Du kan komma åt slutpunkterna (specifika sökvägar/URL:er) både externt och internt. WordPress har redan ett gäng slutpunkter tillgängliga, t.ex. för att hämta inlägg, kategorier, söka på sajten och mer. Se en översikt över standardslutpunkter för WordPress här. Men utvecklare är helt fria att skapa sina egna anpassade slutpunkter med detta API, för att antingen utföra åtgärder eller hämta data.
Vi börjar med det första steget; som skapar anpassade slutpunkter. Om du bara är intresserad av hur man gör förfrågningar, hoppa vidare till den andra delen.
Skapa anpassade slutpunkter
Registrering av anpassade slutpunkter görs i PHP. Du kan lägga till koden till ditt temas functions.phpeller en aktiv plugins kodfil. Gör en funktion kopplad till rest_api_initoch använd funktionen [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()för varje slutpunkt du vill lägga till.
Som den första parametern register_rest_route()måste du tillhandahålla ett unikt namnområde för att se till att dina slutpunkter inte kommer i konflikt med några andra. Använd ditt temas eller plugins slug. Det är vanligt att sedan inkludera ett /följt av ett versionsnummer för din kod. Som ett exempel kommer jag att använda namnutrymmet awhitepixel/v1. Den andra parametern är sökvägen (som följer namnområdet). Slutligen kan du valfritt tillhandahålla en array som tredje parameter med alternativ. I denna array kan du till exempel definiera förfrågningsmetoden (GET, POST eller någon annan), definiera parametrar och viktigast av allt definiera funktionen som ska köras när den slutpunkten efterfrågas.
Som ett minimum bör du ange argumenten ‘metod’ och ‘återuppringning’ (vilket är funktionen för att hantera slutpunktsdata) som tredje parameter. För ‘metod’ kan du ställa in dem som ‘ GET', 'POST', 'PUT', eller någon annan giltig begäranmetod (eller en uppsättning av flera), men jag rekommenderar att du använder WordPress’ standardinställningar för detta. De är följande:
WP_REST_Server::READABLEmetod ‘GET‘WP_REST_Server::EDITABLEmetoderna ‘POST‘, ‘PUT‘ och ‘PATCH‘WP_REST_Server::DELETABLEmetod ‘DELETE‘WP_REST_Server::ALLMETHODSalla ovanstående metoder
Låt oss skapa en grundläggande anpassad slutpunkt som kan nås med GET-förfrågningar:
På raden #2har vi definierat vår anpassade slutpunkt som ‘ awhitepixel/v1/getsomedata‘. Den fullständiga webbadressen skulle vara WordPress REST API rot-URL med prefix, vilket är <yourdomain>/wp-json. Så den fullständiga webbadressen till ovanstående slutpunkt skulle vara ‘ <yourdomain>/wp-json/awhitepixel/v1/getsomedata‘. På raden #4har vi tillhandahållit ett funktionsnamn som callback, som vi kommer att lägga till inom kort.
När du registrerar (eller ändrar) REST API-rutter med register_rest_route(), måste du spola dina permalänkar för att det ska fungera. Du kan göra detta genom att gå till Inställningar > Permalänkar i admin och klicka på Spara.
Vi har ännu inte definierat callback-funktionen – vilket är funktionen för koden som hanterar reaktionen av att använda denna slutpunkt. Den måste returnera ett REST-giltigt svar (i JSON), så du måste returnera något även om slutpunkten inte ska returnera data. Du kan använda funktionsfunktionen [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()eller skapa en instans av WP_REST_Responseobjekt som återuppringningens retur. Som parameter till callback-funktionen får vi ett WP_REST_Requestobjekt som innehåller all information om begäran – inklusive eventuella parametrar. Låt oss skapa en enkel återuppringningsfunktion som helt enkelt skickar lite text som svar:
function awhitepixel_rest_route_getsomedata( $request) {
$response = 'Hello there!';
return rest_ensure_response( $response );
}Detta är det mest grundläggande sättet att skriva en återuppringning. Funktionen rest_ensure_response()ser till att all data vi tillhandahåller (strängen) omvandlas till ett REST-giltigt svar. Uppenbarligen kommer du att vilja lägga till mer kod här, för att antingen göra något i WordPress eller hämta och skicka tillbaka data.
Med ovanstående kod (registrering av endpoint och callback-funktionen) kan du försöka gå till URL:en i din webbläsare och se vad du får. (Kom ihåg att spola dina permalänkar). Om du går till <domain>/wp-json/awhitepixel/v1/getsomedatai webbläsaren visas strängen "Hallå där!".
Acceptera parametrar
Det är mycket vanligt och användbart att tillåta endpoints att acceptera parametrar. Om din webbplats till exempel har produktdata, vill du ha en slutpunkt där du kan ange ett produkt-ID för att få produktens data. Det finns två sätt att gå tillväga. Det vanligaste sättet är att använda GET frågesträng (som läggs till efter URL:en efter en ?, separerade med &i nyckel=värde-format. Till exempel ‘ <endpoint>/product/?product_id=14‘). Alternativt kan du definiera ett "snyggare" URL-mönster, där parametrar är en del av sökvägen. Till exempel ‘ <endpoint>/product/14/‘. Denna sista metod kräver viss kunskap för regexes dock. Vilken metod du ska välja är upp till dig, jag ska visa båda nedan.
GET parametrar
Att definiera möjliga GET-parametrar till din slutpunkt är att använda ‘ args‘-tangenten i register_rest_route()‘s tredje parameter. För varje parameter du vill tillåta, definiera nyckelvärdet (i exemplet ovan ‘ product_id‘) och en uppsättning alternativ för den parametern. Som alternativ kan du definiera parameterns format (om den förväntar sig till exempel ett nummer eller en sträng) och även bestämma om den parametern krävs eller inte.
Som ett exempel vill vi tillåta att vår slutpunkt accepterar ‘ product_id‘ som ett icke-obligatoriskt nummer.
Om du definierar en parameter som sant i required, kommer WordPress att hantera att skicka tillbaka ett 400-felsvar. Likaså om du skickar ett ogiltigt format, till exempel "hej" som värde till en parameter som förväntar sig ett tal.
På rad #15i callback-funktionen ser du hur du får tag på parametervärdet från begäran; med metoden get_param()i det skickade WP_REST_Requestobjektet. Som ett exempel kommer jag att visa olika svar beroende på om det product_idgavs eller inte (kom ihåg att vi har definierat det som valfritt). Logiken i att modifiera din kod enligt de angivna parametrarna är helt upp till dig och ditt projekt. Du kan ha färre slutpunkter som accepterar många parametrar, eller många fler separata slutpunkter för varje specifikt fall.
Med ovanstående kod får jag "Hej där!" när jag besöker <yourdomain>/awhitepixel/v1/getsomedataoch "Returnera produktdata för ID 14" när jag går till <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.
Parametrar som en del av sökvägen
Om du vill tillåta parametrar att vara en del av sökvägen snarare än GET frågesträng, kan du göra det. Du kommer sedan att tillhandahålla ett regexmönster i sökvägen – den andra parametern till register_rest_route().
Att skapa regexmönster kan se ganska kryptiskt ut, men eftersom det är ett helt ämne hittar du enkelt exempel för specifika fall om du googlar det. Jag ska visa ett exempel på att definiera ett regex som accepterar ett antal av vilken längd som helst;
Som du kan se på rad #2 har jag lagt till regexmönstret (?P<product_id>[d]+)i slutet. Detta mönster innebär att vi ska samla ett tal (d) av valfri längd (+) och tilldela det insamlade värdet till parameternyckeln product_id. Och i vår callback-funktion använder vi exakt samma metod som vi gjorde när vi satte upp GET-parametrar; get_param()i WP_REST_Requestobjektet som tillhandahålls för funktionen.
Med ovanstående kod (efter spolning av permalänkar) kan vi besöka webbadressen <yourdomain>/wp-json/awhitepixel/v1/getsomedata/14för att få vårt svar. Denna metod ger förvisso "snyggare" webbadresser, men koden kan lätt bli svårare att läsa och buggfixa. Vilken metod du än väljer är upp till dig.
Återkommer korrekt svar
Tidigare nämnde jag kort hur callback-funktionen behöver returnera ett ordentligt REST-svar. Hittills har vi använt det enklare rest_ensure_response(). Men ibland kanske du vill ha mer kontroll över din slutpunkts avkastning. Du kanske till exempel vill kontrollera HTTP-svarets statuskod. Säg att du skapar en slutpunkt där du kan ange ett produkt-ID och få data för den produkten. Men om det produkt-ID:t inte fanns, eller om andra parametrar orsakar förvirring, kanske du vill returnera en statuskod på till exempel 400 (dålig begäran) eller 404 (hittades inte). Eller kanske 500 (serverfel). Att alltid passera 200 (framgång) trots att begäran var dålig kan orsaka problem i avsändarens slut.
Jag skulle då rekommendera att din callback-funktion returnerar ett WP_REST_Responseobjekt. Med detta objekt kan du styra flera saker, inklusive statuskoden. Det är lättare än du tror! Du skulle i den enklaste formen skapa en ny instans av WP_REST_Response, tillhandahålla en array av data som ska returneras som första parameter och statuskoden som andra parameter. Som ett exempel:
Ovanstående exempel lagrar vi returen av awhitepixel_get_product()funktionen i en variabel. Den här funktionen finns inte, och du bör ersätta den med funktionen som ska hämta (eller göra) de åtgärder du vill ha i ditt projekt. Men säg att funktionen returnerar en tom array och det betyder att något gick fel (till exempel att produkten inte existerade). Vi kunde sedan returnera ett WP_REST_Responseobjekt med statuskod 400, och eventuellt ett meddelande som data som förklarar varför det misslyckades (rad #5-9). Annars returnerar vi data med statuskod 200 Success (rad #10).
Skicka förfrågningar till (anpassade) slutpunkter
Låt oss gå vidare till andra sidan, sändningsdelen: Hur man skickar förfrågningar till våra anpassade slutpunkter. Normalt skulle du skicka WP REST API-förfrågningar med Javascript och här hittar du exempel på användning av jQuery, WordPress-bibliotek och vanilla Javascript. Det är ovanligt, men möjligt, att utföra en REST-förfrågan med PHP också – så jag har tagit med ett exempel på det också.
Det första du bör vara medveten om är att du självklart behöver känna till hela webbadressen för att kunna skicka en förfrågan. Jag rekommenderar inte att hårdkoda domänen (före slutpunkten) eftersom det finns flera sätt att få detta om ditt Javascript fungerar inom WordPress. I äldre versioner av WordPress skulle du behöva använda [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()i PHP och skicka vidare REST-webbadressen som en global Javascript-variabel. Men exemplen nedan visar ett nyare och bättre sätt att få WordPress-webbplatsens REST-rot-URL.
En annan sak att notera är att för ditt projekt skulle du förmodligen avsluta förfrågningarna som ett resultat av någon åtgärd. För att göra det enkelt gör jag alla förfrågningar på DOM redo, så du bör se till att packa in förfrågningskoden i t.ex. som ett resultat av att en besökare klickar på en knapp.
Använder jQuery
Om du har, och vill använda, jQuery-biblioteket kan du använda dess [$.ajax](https://api.jquery.com/jquery.ajax/)()funktion.
Men först en notering om din Javascript-fils beroenden. Uppenbarligen skulle ditt skript behöva 'jquery'som beroende för att ställa det i kö. Men för att enkelt komma åt din WordPress REST-rot-URL, lägg till ett annat beroende; ‘wp-api-request’. Detta säkerställer att Javascript-variabeln wpApiSettings.rootär tillgänglig och innehåller REST API-rotadressen. Här är ett exempel på hur du skulle ställa ditt skript i kö för att illustrera detta beroende;
add_action( 'wp_enqueue_scripts', function() {
wp_enqueue_script(
'awp-javascript-wp-rest',
get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js',
[ 'jquery', 'wp-api-request' ],
null,
true
);
} );Line #5är den intressanta; där vi definierar både jQuery och wp-api-requestsom beroende. Sedan i vår Javascript-fil kan vi utföra en WP REST API-förfrågan så här:
( function( $) {
// Send request
$.ajax( {
url: wpApiSettings.root + 'awhitepixel/v1/getsomedata',
method: 'GET',
data: {
product_id: 14
},
success: function( data) {
console.log( data );
}
} );
} )( jQuery );Detta är så grundläggande som det blir. Vi använder $.ajax()för att skicka en GET-förfrågan till den definierade webbadressen. Som URL använder vi wpApiSettings.rootför att få REST API root URL och sedan lägger vi till den önskade slutpunkten efter den; i vårt fall den anpassade slutpunkten vi skapade tidigare. Valfritt kan vi skicka parametrar i ‘data’. Exemplet ovan passerar product_idmed värdet 14 till slutpunkten. Slutligen i successfunktionen får vi den (lyckade) begäran som parameter och vi är fria att göra vad vi vill med den. I exemplet ovan skriver vi enkelt ut det till konsolen.
Använda WordPress-biblioteket (icke-jQuery)
Om din WordPress-webbplats inte har, eller kan, använda jQuery-biblioteket kan du använda WordPress Javascript-bibliotek för att enkelt utföra en REST API-förfrågan. Funktionen är apiFetchsom är tillgänglig i WordPress globala wpnamnutrymme. wp.apiFetch()är en omslagsmetod för webbläsarens standardfunktion fetch()(som visas härnäst).
Vårt Javascript kommer att behöva beroendet ‘wp-api’ för att kunna använda wp.apiFetch(). Till exempel kan vi ställa skriptet i kö så här:
add_action( 'wp_enqueue_scripts', function() {
wp_enqueue_script(
'javascript-wp-rest',
get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js',
[ 'wp-api' ],
null,
true
);
} );Du hittar det kritiska beroendet på raden #5. Med detta har vi säkerställt att vår Javascript-fil är wp.apiFetch()tillgänglig. Här är ett grundläggande exempel på hur du använder det:
Tänk på att linje #9-13bara är logik för att köra funktionen efter att DOM är klart.
En fördel med att använda wp.apiFetch()över det normala fetch()är att vi kan använda "sökväg" som bara kräver slutpunkten, istället för "url" som kräver hela URL:en. En annan fördel är att den första "kedjan" .then()returnerar data som redan är JSON-formaterad. När du använder originalet .fetch()behöver du fler ".then()-kedjor". Ta en titt på nästa exempel ("Att använda vanilla Javascript") för att se vad jag menar.
Tänk på att fetch()(och som en konsekvens wp.apiFetch()) inte ger ett "rent" sätt att skicka parametrar. Vi kommer att behöva konstruera GET-frågesträngen manuellt i "sökväg", som jag har gjort ovan: '../getsomedata?product_id=14'.
Om du är intresserad av hur man integrerar wp.apiFetchoch anpassar slutpunkter i ett Gutenberg-block, har jag skrivit en separat handledning om detta:
Använder vanilj Javascript
Som ett sista exempel på Javascript-metoder för att skicka förfrågningar till WP REST API finns det ett rent vanilj, icke-WordPress-sätt, med fetch(). Observera att jag använder WordPress global variabel för att få REST-rotadressen. Om du lägger till det här skriptet utanför WordPress, skulle du förmodligen behöva hårdkoda hela webbadressen.
Eftersom jag fortfarande vill ha tillgång till den globala variabeln för WP REST root URL, lägger jag till 'wp-api-request'beroende till min Javascript-köfunktion, så här:
add_action( 'wp_enqueue_scripts', function() {
wp_enqueue_script(
'awp-javascript-wp-rest',
get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js',
[ 'wp-api-request' ],
null,
true
);
} );Och sedan i vår Javascript-fil skulle ett mest grundläggande exempel vara:
Som nämnts ovan ("Att använda WordPress-biblioteket") .fetch()stöder inte ett snyggt, rent sätt att tillhandahålla parametrar. Så du måste manuellt bygga in frågesträngen (“?product_id=14") i URL:en.
Tänk på att hämtningsförfrågan inte direkt returneras med data – den returnerar ett löfte. Det är därför vi måste kedja " .then()" innan vi kan hantera data. Om detta låter obekant för dig rekommenderar jag att du letar upp hur du arbetar med fetch()– det finns gott om förklaringar och exempel på google som kan förklara det bättre än jag.
Om du vill kontrollera REST-svarsstatuskoden på din begäran kan du göra det så här;
I exemplet ovan vid registrering av anpassade slutpunkter nämnde jag hur du kan returnera olika HTTP-statuskoder. Ovanstående kod visar ett exempel på hur man kontrollerar svarets statuskod, som är tillgänglig i det returnerade objektets .statusegenskap. I exemplet ovan kontrollerar jag om statuskoden är något annorlunda än 200 (framgång) vid rad #5. Endast om statuskoden var 200 konverterar jag löftets dataretur till JSON (rad #9).
Använder PHP
Det är mindre vanligt, men fortfarande möjligt, att utföra REST-begäran internt i WordPress med PHP. Här är hur.
För att skicka en WP REST API-förfrågan i PHP skapar vi ett WP_REST_Requestobjekt (exakt som det som skickas till vår callback-funktion tidigare i detta inlägg). I den här objektinstansen definierar vi metod (t.ex. GET) och slutpunktsväg. Valfritt kan vi också lägga till parametrar. Sedan använder vi WordPress funktion [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()med denna begäran instans. Äntligen får vi tag i svaret med [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()funktionen tillgänglig i WP_REST_Server's klass.
Funktionsanropet set_query_params()(linje #3-5) är valfritt och endast nödvändigt om du vill skicka parametrar. Efter den röda tråden i det här inlägget kommer jag att inkludera ett exempel på att överföra funktionens parameter till REST-parameternyckeln product_id.
Linjen #6är dit vi skickar förfrågan. Och på raden #7returnerar vi svarets data. Så om vi skulle anropa denna PHP-funktion, till exempel awp_do_php_rest_request( 14 ), skulle vi då få svaret vi definierade i den slutpunkten (en array med en sträng om du fortfarande använder samma exempel som början av det här inlägget).