WordPress REST API - kompletny przewodnik dla developerów i właścicieli stron

REST API pozwala innemu programowi odczytać lub zmienić dane WordPressa przez HTTP. Odpowiedzi mają zwykle format JSON. Właściciel strony może wykorzystać tę drogę do przekazywania treści do aplikacji, pobierania danych przez system firmowy albo automatyzacji publikacji. Nie trzeba jednak wdrażać osobnego frontendu, aby korzystać z API.

Najpierw określ zasób i operację. Pobranie publicznego wpisu różni się od zmiany jego treści, a odczyt listy produktów od dostępu do zamówień klientów. W WordPressie namespace wp/v2 obejmuje zasoby core. Wtyczki mogą dodawać własne przestrzenie nazw, uprawnienia i formaty odpowiedzi. Nie przenoś automatycznie zasad uwierzytelniania między WordPressem a API WooCommerce.

Rozpisz też kierunek integracji: który system jest źródłem danych, kto je aktualizuje i co ma nastąpić po błędzie. Bez tych ustaleń sprawny endpoint może nadal nadpisywać właściwe dane niewłaściwą wersją. O możliwościach takiego połączenia przeczytasz w ofercie automatyzacji. Samo API nie rozstrzyga konfliktów i nie gwarantuje szybszej strony.

Dla witryny z typowymi bezpośrednimi odnośnikami otwórz adres jej domeny zakończony /wp-json/. To indeks dostępnych tras. Publiczne wpisy znajdziesz zwykle pod /wp-json/wp/v2/posts. Zacznij od odczytu opublikowanych treści, bez nagłówka Authorization i bez danych logowania. Taki test nie powinien niczego zmieniać.

Przy prostych ustawieniach odnośników WordPress może używać parametru ?rest_route=/ zamiast ładnej ścieżki. Nie wpisuj więc na sztywno jednego adresu w każdej instalacji. W kodzie WordPressa użyj funkcji rest_url(), a przy integracji zewnętrznej sprawdź mechanizm wykrywania API oraz adres zwracany przez witrynę.

Oceń odpowiedź: kod HTTP, Content-Type i zawartość JSON. Strona HTML z formularzem logowania lub komunikatem ochrony nie jest prawidłową odpowiedzią API tylko dlatego, że serwer zwrócił 200. Jeżeli testujesz własne rozszerzenie, zacznij na kopii. Konfiguracja Local WP pomaga przygotować środowisko, w którym możesz bezpiecznie obserwować strukturę odpowiedzi.

Typowe zasoby core to posts, pages, media, categories i tags. GET służy do odczytu. Operacje tworzenia, aktualizacji oraz usuwania wymagają odpowiedniego żądania i uprawnień. Nie sprawdzaj działania integracji przez przypadkowe usunięcie lub edycję produkcyjnego wpisu. Przygotuj osobny materiał testowy na kopii.

W dokumentacji paginacji WordPressa parametr per_page przyjmuje wartości od 1 do 100. Większy zbiór pobiera się kolejnymi stronami. Nagłówki X-WP-Total i X-WP-TotalPages informują odpowiednio o liczbie rekordów i stron. To ważne przy imporcie: pierwsza odpowiedź nie musi zawierać całej kolekcji.

Parametr _fields pozwala ograniczyć odpowiedź do potrzebnych pól. Wybieraj tylko dane używane przez integrację, ale sprawdź dokumentację konkretnego zasobu. Nie każdy endpoint obsługuje identyczne filtry. Zapisuj stan postępu importu, kontroluj błędy i unikaj równoczesnego wysyłania dużej liczby żądań. Przy ponawianiu operacji zapisu zadbaj o rozpoznawanie już utworzonych rekordów, aby przerwana synchronizacja nie produkowała duplikatów.

Publiczny odczyt opublikowanych treści często nie wymaga uwierzytelnienia. W interfejsie działającym wewnątrz WordPressa używa się sesji zalogowanego użytkownika oraz nonce. WordPress REST API Handbook wskazuje akcję wp_rest i nagłówek X-WP-Nonce. Bez nonce żądanie może zostać potraktowane jako anonimowe mimo aktywnej sesji w przeglądarce.

Nonce pomaga chronić przed CSRF. Nie jest hasłem ani dowodem, że użytkownik ma prawo zmienić konkretny wpis. Serwer nadal sprawdza jego uprawnienia. Nie udostępniaj publicznie operacji zapisu tylko dlatego, że otrzymała nonce.

Dla zewnętrznej integracji serwerowej WordPress od wersji 5.6 ma Application Passwords. Korzystaj z HTTPS i osobnego użytkownika o możliwie małych uprawnieniach. Sekret przechowuj po stronie serwera, np. w przeznaczonym do tego magazynie konfiguracji. Nie umieszczaj go w JavaScript dostarczanym do przeglądarki, repozytorium ani logach. Base64 nie szyfruje hasła.

Dokumentacja haseł aplikacji opisuje osobne odwołanie credentialu. Dzięki temu można odłączyć jedną integrację bez zmiany głównego hasła użytkownika. JWT i OAuth wymagają dodatkowej implementacji; nie są automatycznie dostępne w każdej instalacji.

Własną trasę rejestruje się przy rest_api_init. Musi mieć określone metody, callback oraz permission_callback. Instrukcja dodawania endpointów wyjaśnia również walidację i sanitizację argumentów. To osobne zadania: poprawny format identyfikatora nie oznacza jeszcze prawa do odczytu wskazanego rekordu.

Dla publicznego endpointu świadomie ogranicz odpowiedź do informacji przeznaczonych dla każdego odwiedzającego. Nie zwracaj danych klientów, adresów email, ustawień integracji ani sekretów. permission_callback ustawione na __return_true oznacza publiczną dostępność i ma sens wyłącznie przy takim jawnym zakresie. Nie kopiuj tej wartości do trasy obsługującej zamówienia.

Dla operacji chronionej callback uprawnień powinien sprawdzać możliwość wykonania danej czynności, np. edycji wskazanego wpisu, przez current_user_can(). Nie wystarczy sprawdzenie, że ktoś jest zalogowany. Konto subskrybenta nie powinno otrzymać praw redaktora. Waliduj wymagane pola, zakresy wartości oraz istnienie zasobu. Zwracaj czytelne błędy, ale bez danych uwierzytelniających i szczegółów konfiguracji serwera.

Przy 401 sprawdź, czy żądanie zostało uwierzytelnione i czy nagłówek Authorization dociera do WordPressa. Przy 403 zweryfikuj uprawnienia, nonce oraz odpowiedź warstwy ochrony. Sam numer nie przesądza o przyczynie: zapisz także kod błędu zwrócony w JSON. Odpowiedź Cloudflare lub hostingu może wyglądać inaczej niż błąd WordPressa.

Przy 404 sprawdź domenę, ścieżkę, namespace, metodę i obecność wtyczki rejestrującej trasę. Jeżeli działa odczyt posts, a nie działa endpoint rozszerzenia, nie zaczynaj od przeinstalowania całego WordPressa. Porównaj trasę z indeksem API i dokumentacją dodatku.

CORS reguluje zachowanie przeglądarki, nie zastępuje kontroli uprawnień po stronie serwera. Globalne wyłączenie API także nie jest naprawą. Dokumentacja WordPressa mówi: "You should not disable the REST API" (FAQ REST). Zależne funkcje panelu i wtyczek mogą przestać działać. W razie awarii wybierz diagnozę WordPressa zamiast przypadkowego blokowania kolejnych tras.

Odpowiedź users wymaga ostrożnej interpretacji. W schemacie użytkownika pole username ma kontekst edit. Publiczna nazwa lub slug autora nie jest tym samym polem. Nie oznacza to, że można udostępniać własne metadane użytkowników bez kontroli. Każde rozszerzenie odpowiedzi trzeba ocenić pod kątem tego, kto ma je widzieć.

Przed wdrożeniem zapisz zakres danych, role konta integracji, sposób odwołania dostępu i reakcję na nieudaną synchronizację. Sprawdź odczyt oraz zapis na kopii, a potem kontrolowany zakres produkcyjny. Sekrety przekazuj bezpiecznym kanałem uzgodnionym przy wdrożeniu, nigdy przez publiczny formularz lub treść zgłoszenia.

Jeżeli potrzebujesz połączyć WordPress z innym systemem, napisz do nas. Na pierwszy kontakt wystarczą nazwy platform i opis procesu. Dokumentacja, przykładowy format danych bez informacji klientów i częstotliwość synchronizacji pomogą później. Wsparcie WordPress może objąć istniejącą integrację, własny endpoint albo naprawę konkretnej operacji; zakres ustala się po rozpoznaniu problemu.

REST API przydaje się przy integracjach strony z innymi systemami. Takie połączenia planujemy już na etapie, gdy zamawiasz stronę internetową dla firmy.