W tym wpisie poznamy WordPress REST API. Na początek zdefiniujmy pojęcia oraz podsumujmy kiedy WordPress REST API może nam się przydać.
Czym jest API?
API (ang Application Programming Interface) to oprogramowanie, które umożliwia komunikację z innymi programami w limitowany i uporządkowany sposób. API pozwala współdzielić dane i wysyłać komunikaty.
Kiedy przykładowo korzystamy z bramek płatności, to API jest odpowiedzialne za to aby aby zweryfikować płatność i zaktualizować status naszego zamówienia w sklepie. Jeżeli korzystamy z funkcji logowania za pośrednictwem serwisu społecznościowego to API wysyła do aplikacji potrzebne dane uwierzytelniające użytkownika itd…
Co oznacza REST?
REST (ang. Representational State Transfer) – to styl architektoniczny budowania API. REST zaprojektowano z myślą o wydajnej wymianie danych na drodze klient – serwer.
Biorąc pod uwagę, że WordPress jest systemem CMS, po wytłumaczeniu fundamentalnych definicji automatycznie klaruje nam się definicja WordPress REST API
WordPress REST API – co to jest?
WordPress REST API to interfejs programistyczny, który umożliwia interakcję z witryną WordPress za pomocą pobierania i wysyłania obiektów JSON w celu odczytywania i zarządzania treściami strony internetowej.
W praktyce oznacza to, że za pomocą WordPress REST API można zbudować nowy, interaktywny interfejs lub przenieść zawartość strony do osobnej aplikacji. WordPress trzyma dane a za pomocą dowolnej technologii czy języka programowania, możemy zrobić własny i niezależny Front-End samej strony a także panelu do edycji postów. Oznacza to że możemy zrobić aplikację na Androida czy iOS bazującą na danych pochodzących z Back-Endu WordPress.
Kiedy korzystamy z REST API powinniśmy nieco zmodyfikować naszą nomenklaturę i zamiast określenia „strona” stosować słowo „aplikacja”.
WP REST API Implementuje dokładnie te same zabezpieczenia i mechanizmy kiedy standardowo korzystamy z systemu WordPress – dane publiczne są dostępne publicznie a dane prywatne lub informacje o użytkownikach są chronione hasłem.
WordPress REST API w praktyce
Aby zobaczyć jak działa WordPress REST API wystarczy wywołać jakiś endpoint. np. wchodząc na adres:
https://mansfeld.pl/wp-json/wp/v2/posts
…otrzymamy dane dotyczące publicznych postów. Jeżeli nigdy nie miałeś do czynienia z danymi w formacie JSON, możesz wejść na stronę: https://jsoneditoronline.org/ i wkleić w lewe okno całą zawartość jaka pojawiła się w przeglądarce. Po kliknięciu w przycisk „Copy” naszym oczom ukaże się uporządkowany w hierarchię zestaw danych zawartych w poszczególnych postach. Jeżeli chcesz się lepiej oswoić z tym formatem, zapraszam do artykułu o tym dlaczego wykorzystujemy i co to jest JSON.
Takie dane możemy teraz przetwarzać – np. pobrać je do stworzenia aplikacji, która będzie bazować na treściach z tej strony. Kiedy już zrozumiesz, że zwracany przez WordPressa tekst jest pewnym zbiorem danych, możemy przejść do kolejnych ćwiczeń.
Istnieje też kolejna aplikacja, która będzie pomocna jest to Postman: https://www.postman.com/ Możesz ją pobrać i dzięki temu praca z API będzie efektywniejsza. Istnieją też pluginy do przeglądarek, które prezentują dane JSON w przyjaźniejszej formie.
Punkty końcowe (Endpoint)
W pierwszym przykładzie posłużyliśmy się punktem końcowym. Poszczególne punkty końcowe dostarczają konkretne dane. Na sam początek sprawdźmy jakie inne publiczne endpointy mamy do dyspozycji:
| Posty | /wp-json/wp/v2/posts |
| Kategorie | /wp-json/wp/v2/categories |
| Tagi | /wp-json/wp/v2/tags |
| Strony | /wp-json/wp/v2/pages |
| Komentarze | /wp-json/wp/v2/comments |
| Media | /wp-json/wp/v2/media |
| Użytkownicy | /wp-json/wp/v2/users |
| Typy postów | /wp-json/wp/v2/types |
| Wyszukiwarka | /wp-json/wp/v2/search |
Uwaga: Aby własne typy postów i taksonomie były widoczne w REST API należy użyć dodatkowych argumentów podczas ich rejestrowania między innymi show_in_rest. Więcej informacji w źródłach.
Pobieranie danych z REST API w praktyce
Czas wykorzystać zdobytą wiedzę w praktyce. Zróbmy prostą aplikację JavaSript, która będzie dynamicznie generowana dzięki integracji z naszym WP REST API. Pobierzmy listę postów z ich oryginalnymi linkami, obrazkiem i zajawkami. Taką funkcjonalność można wykorzystać np. po to aby wykonać Infinite-Scroll na własnej stronie lub jakąś lekką bezserwerową wersję naszego bloga.
Jeżeli nie otrzymujesz odpowiedzi JSON na swojej stronie WordPress, zaktualizuj WordPressa do najnowszej wersji (lub co najmniej 4.7)
Jak już wspomniałem, do pobierania postów służy punkt końcowy /wp-json/wp/v2/posts/
Możemy posługiwać się specjalnymi parametrami. Jeżeli chcemy wybrać tylko jeden post możemy użyć parametru per_page:
https://mansfeld.pl/wp-json/wp/v2/posts?per_page=3
Możemy też ograniczyć zakres tematyczny posługując się numerem ID konkretnej kategorii, np. aby wybrać posty z kategorii „programowanie” należy użyć takiego punktu końcowego:
https://mansfeld.pl/wp-json/wp/v2/posts?categories=172
Parametry można ze sobą łączyć, przykładowo ten punkt końcowy zwróci nam posty z kategorii o ID 172 i ograniczy się do jednego postu:
https://mansfeld.pl/wp-json/wp/v2/posts?categories=172&per_page=1
Jeżeli interesuje nas post o konkretnym ID możemy wykonać takie zapytanie:
https://mansfeld.pl/wp-json/wp/v2/posts?include[]=16617
Tworzenie osobnej strony
Na początek warto zrobić szablon podstawowej strony. Jeżeli chcesz, możesz użyć ulubionych bibliotek a nawet dowolnego frameworka JS typu Vue.js, Angular czy React. W tym przykładzie kod będę pisał w czystym JavaScript aby był uniwersalny.
Sprawdźmy czy wszystko działa dodając do roboczego elementu DIV jakiś tekst:
<!DOCTYPE HTML>
<html lang="pl-PL">
<head>
<title>WP REST API Test</title>
</head>
<body>
<h1>WP REST API</h1>
<div id="data">
</div>
<script>
data = document.getElementById("data");
data.innerHTML = 'Tutaj pojawią się dane';
</script>
</body>
</html>
Pobieranie i parsowanie danych JSON
Użyjmy teraz metody GET za pomocą AJAX. Wykonanie tego w czystym JavaScrit nie powinno nikomu przysporzyć problemów.
Pamiętaj, że jeżeli wysyłasz zapytania z innego serwera lub z pliku lokalnego na swoim komputerze (z innego origin) musisz ustawić odpowiednie nagłówki na serwerze zgodnie z wymogami CORS. Czytaj więcej o CORS oraz jak go objeść w osobnym artykule.
W WordPressie nagłówki CORS można wysłać dodając do pliku functions.php (lub tworząc własną wtyczkę) taki kod:
function rest_cors() {
remove_filter( 'rest_pre_serve_request', 'rest_send_cors_headers' );
add_filter( 'rest_pre_serve_request', function( $value ) {
header( 'Access-Control-Allow-Origin: *' );
header( 'Access-Control-Allow-Methods: GET' );
header( 'Access-Control-Allow-Credentials: true' );
header( 'Access-Control-Expose-Headers: Link', false );
return $value;
});
}
add_action( 'rest_api_init', 'rest_cors', 15 );
Zawartość wewnątrz <script> podmieniam na taki kod:
var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://mansfeld.pl/wp-json/wp/v2/posts?categories=172');
xhr.onload = function() {
if (xhr.status >= 200 && xhr.status < 400) {
var data = JSON.parse(xhr.responseText);
loadData(data);
}
else {
console.log("Połączono z serweere ale wystąpił błąd");
}
};
xhr.onerror = function(){
console.log("Bład połączenia z serwerem");
}
xhr.send();
function loadData(wpData){
var html = '';
for (i = 0; i < wpData.length; i++){
html += '<h2>' + wpData[i].title.rendered + '</h2>';
}
posts = document.getElementById("posts");
posts.innerHTML = html;
}
Jak widać, wszystko działa:
Właśnie bez konieczności posiadania back-endu wyświetliliśmy ostatnie tematy artykułów o programowaniu z mojego bloga.
Uzupełnijmy ten przykład dla przećwiczenia korzystania z pól JSON. W pętli for odpowiedzialnej za generowanie kodu HTML umieśćmy dodatkowe elementy np. z datą linkiem i zajawką:
html += '<h2><a href="'+ wpData[i].link +'">' + wpData[i].title.rendered + '</a></h2>';
html += '<small> Utworzono: ' + wpData[i].date + '</small>';
html += '<p>' + wpData[i].excerpt.rendered + '</p>';
Całość powinna dać nam coś takiego:
Wystarczy dodać styl CSS aby wszystko lepiej się prezentowało i już mamy prosty agregator treści lub asynchroniczny widget z ostatnimi artykułami, który można umieścić w dowolnym miejscu na stronie. Zmieniając endpoint, możemy pobrać dane z innej kategorii lub przykładowo wyświetlić komentarze.
CRUD w WordPress w REST API
CRUD to skrót od Create Read Update Delete. Zobaczmy jak przebiega tworzenie, aktualizowanie i usuwanie danych w REST API.
Uwaga: Aby manipulować danymi WordPress z zewnętrznej aplikacji, będziemy musieli w zapytaniu POST przesłać dane do logowania lub nonce. Stąd, zalecam tego typu funkcjonalności programować po stronie serwera (aby nie publikować loginów i haseł w kodzie dostępnym publicznie).
Publikowanie postów WordPress za pomocą REST API
Aby móc dodać treści potrzebujemy standardowego formularza.
<input type="text" name="title" id="title"> <textarea type="text" name="content" id="content"></textarea> <button id="publish">Opublikuj</button>
Ja posłużę się stylem z mojej obecnej strony. Całość wygląda tak:
Teraz czas na kod zajmujący się wysłaniem odpowiedniego zapytania POST:
var submit = document.querySelector('#publish'); submit.addEventListener('click', function(){
var publishData = {
'title' : document.querySelector('#title').value,
'content' : document.querySelector('#content').value,
'status' : 'publish'
}
var publish = new XMLHttpRequest();
publish.open("POST", 'https://mansfeld.pl/wp-json/wp/v2/posts');
publish.setRequestHeader('X-WP-Nonce', '<?php echo wp_create_nonce("wp_rest"); ?>');
publish.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
publish.send(JSON.stringify(publishData));
});Na początku wykrywamy klik i pobieramy odpowiednie wartości z formularza. Tworzymy obiekt ze zmiennymi. Zauważ, że wykonujemy zapytanie POST do tego samego punktu końcowego, którym posługiwaliśmy się w przypadku pobierania postów za pomocą GET.
Teraz musimy powiedzieć serwerowi, że wysyłamy dane w formacie JSON. Mimo, że WordPress pilnuje aby osoba wykonująca post miała odpowiednie uprawnienia, musimy dodać nagłówek X-WP-Nonce, który zawiera specjalny jednorazowy klucz, który jest potrzebny do wykonania takiego działania.
Jeżeli nie masz dostępu do PHP i natywnej funkcji wp_create_nonce() zapoznaj się z aleternatywnymi metodami uwierzytelniania w źródłach.
Sprawdźmy czy to działa
Wpisuję przykładowy tytuł, treść i klikam w „Opublikuj”.
Alternatywne metody uwierzytelniania
W tym najprostszym przykładzie publikowania posta użyłem metody uwierzytelniania za pomocą nonce, którą pobrałem z back-endu. Czy są jeszcze jakieś inne metody uwierzytelnienia aby można było opublikować post z całkiem osobnej strony? Oczywiście.
Jedną z nich jest przesłanie loginu i hasła do kokpitu WordPress. Jeżeli jest to niedostępna publicznie aplikacja to można taką metodę wykorzystać bez ryzyka narażania strony na atak. Można do tego wykorzystać wtyczkę JSON Basic Authentication a przypadek użycia podlinkowałem w źródłach.
Dodatek 1: Advanced Custom Fields (ACF) w WP REST API
Aby wygodnie wyciągać własne pola stworzone za pomocą wtyczki Advanced Custom Fields musimy zainstalować koelejną wtyczkę ACF to REST API autorstwa Aires Gonçalves. Pola będą wówczas osiągalne z poziomu postów i własnych typów (jeżeli istnieją) oraz za pomocą dodatkowych endpointów:
Podsumowanie
Jak widać, posługiwanie się REST API w WordPressie nie należy do szczególnie trudnych zadań. Jeżeli opanowałeś podstawy WordPressa i chcesz się na poważnie zajmować nowoczesnymi aplikacjami, które używają go tylko jako back-end programistyczny, opanowanie tego interfejsu otworzy przed Tobą całkiem nowe możliwości, które już wkrótce mogą stać się standardem.
Źródła
- https://developer.wordpress.org/rest-api/
- https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-rest-api-support-for-custom-content-types/
- https://developer.wordpress.org/rest-api/reference/
- https://rudrastyh.com/wordpress/rest-api-create-delete-posts.html#basic_auth
Odpowiedz lub skomentuj