JSON API w WordPressie – co warto wiedzieć?

WordPress REST API to wbudowany interfejs, który udostępnia treści Twojej strony jako dane JSON pod adresem /wp-json/. Zamiast generować gotowy HTML, serwer zwraca surowe dane (wpisy, strony, użytkownicy, produkty), które może pobrać dowolny system: aplikacja mobilna, frontend w React czy zewnętrzny program.

JSON (JavaScript Object Notation) to lekki format wymiany danych oparty na parach klucz-wartość. Jest czytelny dla człowieka i natywnie obsługiwany przez JavaScript oraz wszystkie popularne języki (PHP, Python, Java, Go). Dlatego stał się standardem komunikacji w nowoczesnych API, wypierając cięższy XML.

REST API zostało włączone do rdzenia WordPressa w wersji 4.7 (grudzień 2016). Wcześniej działało jako wtyczka. Od tego czasu jest domyślnie aktywne na każdej instalacji – wystarczy mieć włączone ładne odnośniki (permalinki), by zacząć z niego korzystać.

Prosty test: wpisz w przeglądarce adres-twojej-strony.pl/wp-json/wp/v2/posts. Jeśli zobaczysz tablicę obiektów z wpisami, API działa. To samo żądanie GET stoi za większością integracji, o których piszemy dalej.

REST API i WPGraphQL rozwiązują ten sam problem (pobieranie danych z WordPressa), ale w odmienny sposób. REST udostępnia sztywne endpointy – każdy zwraca ustalony zestaw pól. GraphQL pozwala klientowi w jednym zapytaniu poprosić dokładnie o te pola, których potrzebuje, i to z wielu zasobów naraz.

Klasyczny problem REST to over-fetching i under-fetching. Żądanie /wp-json/wp/v2/posts zwraca pełne obiekty wpisów, nawet jeśli aplikacja mobilna potrzebuje tylko tytułu i daty (over-fetching). Z drugiej strony, żeby dociągnąć autora i kategorie, często trzeba wykonać kolejne żądania (under-fetching, problem N+1). GraphQL eliminuje oba – jedno zapytanie, jeden response z wybranymi polami.

Cena za tę elastyczność: WPGraphQL to dodatkowa wtyczka, którą trzeba zainstalować, utrzymywać i zabezpieczyć. Wprowadza też własną warstwę cache i krzywą uczenia dla zespołu. REST jest natomiast wbudowany, stabilny i nie generuje długu technologicznego.

Headless WordPress to architektura, w której WordPress pełni rolę wyłącznie backendu (CMS), a frontend budujesz osobno – w React, Next.js, Vue lub jako stronę statyczną. Panel administracyjny i edytor działają normalnie, ale to nie WordPress generuje HTML dla odwiedzającego. Robi to zewnętrzna aplikacja, która pobiera dane przez REST API lub WPGraphQL.

W tradycyjnym modelu łańcuch wygląda tak: użytkownik wchodzi na stronę, WordPress wykonuje PHP, generuje HTML i wysyła go do przeglądarki. W headless ten łańcuch jest rozdzielony – CMS i prezentacja są od siebie niezależne.

To nie jest ulepszenie domyślne, tylko inna architektura z konkretnymi zastosowaniami. Ma sens, gdy potrzebujesz ekstremalnej wydajności (strony statyczne z CDN), dostarczania treści na wiele kanałów jednocześnie (web, aplikacja, kiosk), pełnej swobody w budowie interfejsu albo gdy Twój zespół pracuje w React/Vue i nie zna PHP.

Ma też realne koszty. Tracisz większość ekosystemu wtyczek, które działają z frontendem PHP (formularze, cache stron, część SEO). Rośnie złożoność – dwa systemy do utrzymania, hosting frontendu, osobny deployment. Dla zwykłej strony firmowej czy bloga headless to zwykle przerost formy nad treścią.

Najczęstsze zastosowanie to zasilanie aplikacji mobilnej treściami z WordPressa. Redakcja publikuje wpis w panelu, a aplikacja pobiera go przez /wp-json/wp/v2/posts – jedno źródło treści, wiele kanałów dystrybucji.

Drugi typowy scenariusz to integracje między systemami. REST API pozwala synchronizować dane z CRM, systemem ERP, narzędziem do mailingu czy zewnętrzną platformą. Nowe zamówienie w WooCommerce może automatycznie trafić do systemu księgowego, a status z magazynu – wrócić na stronę.

Trzecie zastosowanie to budowa aplikacji SPA (Single Page Application) i interaktywnych frontendów, które dynamicznie ładują treści bez przeładowania strony. To także podstawa headless oraz importu i eksportu danych przy migracjach.

Warto pamiętać o jednej rzeczy, którą rzadko opisują poradniki: REST API obejmuje też endpointy do zapisu (POST, PUT, DELETE), nie tylko odczytu. Oznacza to, że źle zabezpieczone API może pozwolić na tworzenie i modyfikowanie treści z zewnątrz. Dlatego konfiguracja uwierzytelniania to nie opcja, lecz wymóg.

Domyślnie WordPress używa uwierzytelniania ciasteczkowego (cookie). Po zalogowaniu do panelu te same ciasteczka autoryzują żądania REST API w obrębie tej samej domeny. To działa dla motywów i wtyczek, ale nie sprawdzi się dla zewnętrznej aplikacji mobilnej czy integracji serwer-serwer.

Do komunikacji z zewnątrz WordPress oferuje hasła aplikacji (Application Passwords) – wbudowane od wersji 5.6. Generujesz dedykowane hasło dla konkretnej aplikacji w profilu użytkownika i używasz go w nagłówku uwierzytelniania podstawowego (Basic Auth), zawsze po HTTPS. Hasło można w każdej chwili odwołać bez zmiany hasła głównego.

Dla bardziej rozbudowanych projektów stosuje się tokeny JWT (przez wtyczkę) lub OAuth. Niezależnie od metody, kilka zasad jest stałych: wymuszaj HTTPS, ogranicz uprawnienia kont integracyjnych do minimum, kontroluj CORS przy żądaniach międzydomenowych i rozważ wyłączenie publicznego listowania użytkowników (/wp-json/wp/v2/users), które bywa wykorzystywane do enumeracji loginów.

REST API może obciążyć serwer, jeśli używasz go bez umiaru. Domyślnie odpowiedzi są stronicowane (po 10 elementów), ale duże zapytania o setki rekordów z pełną treścią potrafią spowolnić bazę. W praktyce ograniczamy zwracane pola parametrem _fields, włączamy cache odpowiedzi (np. na poziomie obiektu lub strony) i unikamy odpytywania API przy każdym ruchu użytkownika tam, gdzie wystarczy odświeżać dane cyklicznie.

Najczęstszy problem, z jakim spotykają się właściciele stron, to komunikat o błędzie JSON w edytorze blokowym. Zwykle nie jest to wina samego API – to objaw głębszego problemu. Cztery typowe przyczyny: zepsute permalinki, nieprawidłowo skonfigurowany certyfikat SSL i wymuszanie HTTPS, zbyt agresywny firewall lub reguły bezpieczeństwa serwera blokujące żądania, oraz konflikt wtyczki bądź motywu.

Pierwszy krok diagnostyki jest banalnie prosty i często wystarcza: przejdź do Ustawienia, Bezpośrednie odnośniki i zapisz ustawienia ponownie (bez zmian) – to przebudowuje reguły przepisywania adresów. Jeśli to nie pomoże, sprawdź, czy /wp-json/ odpowiada poprawnie, a następnie metodą eliminacji wyłączaj wtyczki. Dla integracji warto budować własne endpointy zamiast nadużywać domyślnych – daje to kontrolę nad zwracanymi danymi i wydajnością.

Gdy potrzebujesz wdrożyć integrację, headless lub aplikację opartą o WordPressa, pomagamy zaprojektować architekturę i bezpieczeństwo API – sprawdź naszą ofertę strony internetowe lub umów bezpłatną konsultację.

W naszych wdrożeniach najczęściej widzimy, że firmy sięgają po headless WordPress, zanim faktycznie go potrzebują – kuszą je hasła o szybkości i nowoczesnym frontendzie. W większości projektów dobrze zoptymalizowany klasyczny WordPress z cache i dobrym hostingiem daje wynik nieodróżnialny dla użytkownika, a kosztuje ułamek tego co utrzymanie dwóch systemów.

Naszą regułą jest prosta kolejność decyzji: najpierw pytamy, czy treść musi trafiać do więcej niż jednego kanału (web plus aplikacja, kiosk, inny serwis). Jeśli nie – zostajemy przy tradycyjnym modelu i ewentualnie wystawiamy pojedyncze własne endpointy REST tam, gdzie potrzebna jest integracja. Headless rezerwujemy dla projektów, w których multichannel albo ekstremalna wydajność to twardy wymóg biznesowy, nie ambicja techniczna.