WordPress REST API vs. GraphQL w 2026: Architektoniczne starcie

O decyzji przesądzają dziś wymagania inżynierskie, które da się zmierzyć: ile żądań potrzebuje strona, ile JSON-a musi sparsować przeglądarka, jak odpowiedzi trafiają do cache na brzegu sieci, skąd frontend bierze typy i kto utrzymuje dodatkowy kod. Obie opcje są dojrzałe. Ten przewodnik porównuje je w tych punktach, a każdą nazwę API, ustawienie i wartość domyślną sprawdziliśmy w REST API Handbook i w dokumentacji WPGraphQL.

#1. Różnice między REST API a GraphQL w WordPressie

REST (endpoint-driven)
  GET /wp-json/wp/v2/posts/101
  GET /wp-json/wp/v2/users/4
  GET /wp-json/wp/v2/categories?post=101
  = several HTTP requests, each with a fixed response shape

GraphQL (document-driven)
  POST /graphql
  query SinglePost {
    post(id: "101", idType: DATABASE_ID) {
      title
      date
      author { node { name } }
      categories { nodes { name slug } }
    }
  }
  = one HTTP request, the client names every field it wants

REST API opiera się na stałych zasobach. Żądanie do /wp-json/wp/v2/posts zwraca pełną reprezentację wpisu: wyrenderowaną treść, zajawkę, GUID, status komentarzy, linki i więcej. WPGraphQL odwraca ten model. Klient wysyła dokument zapytania, a serwer zwraca tylko pola, które ten dokument wymienia.

#Over-fetching i under-fetching w REST API

Zespół WPGraphQL opisuje problem REST jako jednoczesny over-fetching i under-fetching: endpoint wpisów zwraca identyfikatory kategorii i tagów, treść i zajawkę, których widok listy nie potrzebuje, a mimo to brakuje w nim nazwy i awatara autora, co wymaga kolejnych żądań (WPGraphQL vs WP REST API).

Rdzeń ma na to dwie odpowiedzi, często pomijane. Globalny parametr _fields zwraca tylko część pól, na przykład ?_fields=id,title,link, a od WordPressa 5.3 obsługuje też właściwości zagnieżdżone, takie jak pojedynczy klucz meta. Parametr _embed dołącza powiązane zasoby (autora, obrazek wyróżniający, terminy) do tej samej odpowiedzi, a od WordPressa 5.4 możesz go ograniczyć do wybranych relacji linków (Global parameters). Z oboma parametrami widok listy w REST może zbliżyć się do rozmiaru odpowiedzi z GraphQL. Tym, czego REST nadal nie ma, jest typowany schemat, względem którego klient może budować zapytania.

#2. Zalety i wady WordPress REST API

WordPress REST API jest częścią rdzenia od dekady i jest bardziej solidne niż kiedykolwiek.

• Siła: działa od razu. Nie wymaga dodatkowych wtyczek do podstawowej funkcjonalności. Dobrze się cachuje na poziomie HTTP przy użyciu standardowych CDN-ów, bo każdy zasób ma własny adres URL.
• Słabość: domyślny over-fetching. Jeśli potrzebujesz tylko tytułu i sluga wpisu, a zapomnisz o _fields, REST wyśle cały obiekt wpisu razem z treścią i metadanymi. To marnuje pasmo, szczególnie na urządzeniach mobilnych.

REST API używa JSON-a w żądaniach i odpowiedziach, więc może z niego korzystać każdy język, który potrafi wysyłać żądania HTTP i czytać JSON (REST API Handbook). Dlatego niemal każda platforma integracyjna, konektor CRM i odbiorca webhooków mówi najpierw po REST.

#3. Zalety i wady WPGraphQL

GraphQL (zazwyczaj wdrażany przez WPGraphQL) pozwala programiście frontendu zdefiniować kształt odpowiedzi.

• Siła: jedno żądanie, dokładnie te dane, których chcesz. Możesz pobrać wpis, jego kategorie, 3 ostatnie wpisy autora i ustawienia strony w jednym cyklu sieciowym. Schemat jest silnie typowany, a każde pole deklaruje swój typ.
• Słabość: wymaga utrzymywania dodatkowej wtyczki. Złożone zapytania mogą czasem prowadzić do wolnych odczytów z bazy danych, jeśli nie są zoptymalizowane za pomocą object cache (Redis).

Dane wtyczki, odczytane z katalogu wtyczek wordpress.org 14 października 2026: WPGraphQL 2.24.0, wymaga WordPressa 6.0 i PHP 7.4, testowana do WordPressa 7.0.7, ponad 30 000 aktywnych instalacji. Strona wtyczki informuje, że WPGraphQL staje się wtyczką kanoniczną (Canonical Plugin) na WordPress.org. Wtyczka stosuje wersjonowanie semantyczne, więc zmiana numeru wersji głównej sygnalizuje zmiany niekompatybilne wstecz i przed aktualizacją warto przeczytać informacje o wydaniu.

#4. Jak WPGraphQL rozwiązuje problem N+1

Naiwny resolver dla zapytania o 20 ostatnich wpisów i nazwę autora każdego z nich wykonuje jedno zapytanie o wpisy, a potem po jednym zapytaniu na autora. To jest problem N+1. WPGraphQL omija go wzorcem DataLoader: w trakcie rozwiązywania zapytania zbiera potrzebne identyfikatory (na przykład wszystkie wartości post_author) i ładuje je jedną paczką. W przykładzie z dokumentacji WPGraphQL liczba zapytań SQL o autorów pięciu wpisów spada z pięciu do jednego (WPGraphQL vs WP REST API).

SELECT * FROM wp_users WHERE ID IN (2, 5, 8, 14);

Do tego WPGraphQL ma warstwę modelu (Model Layer): zestaw klas PHP, które opakowują obiekty WordPressa i sprawdzają wrażliwe pola, takie jak adres e-mail użytkownika, zanim zostaną zwrócone (WPGraphQL concepts).

#Jak rozszerzyć schemat WPGraphQL w PHP

<?php
declare(strict_types=1);

add_action('graphql_register_types', function (): void {
    register_graphql_object_type('PerformanceMetrics', [
        'description' => __('Measured Core Web Vitals for a post', 'wppoland'),
        'fields' => [
            'lcpSeconds' => ['type' => 'Float'],
            'inpMilliseconds' => ['type' => 'Int'],
            'clsScore' => ['type' => 'Float'],
        ],
    ]);

    register_graphql_field('Post', 'cwvMetrics', [
        'type' => 'PerformanceMetrics',
        'resolve' => function ($post): ?array {
            $raw = get_post_meta($post->databaseId, '_wppoland_cwv_data', true);
            if (!is_array($raw)) {
                return null;
            }
            return [
                'lcpSeconds' => isset($raw['lcp']) ? (float) $raw['lcp'] : null,
                'inpMilliseconds' => isset($raw['inp']) ? (int) $raw['inp'] : null,
                'clsScore' => isset($raw['cls']) ? (float) $raw['cls'] : null,
            ];
        },
    ]);
});

#5. Jak stworzyć własny endpoint REST w WordPressie

Podstawowy wzorzec to register_rest_route() na haku rest_api_init albo klasa rozszerzająca WP_REST_Controller. Zasady z handbooka, które mają znaczenie na produkcji (Adding custom endpoints):

• Od WordPressa 5.5 trasa zarejestrowana bez permission_callback wywołuje komunikat _doing_it_wrong. Dla publicznego endpointu przekaż jawnie __return_true.
• Przestrzenie nazw powinny trzymać się wzorca vendor/v1, a wersję podnosisz, gdy łamiesz kompatybilność.
• Błąd to WP_Error z kodem HTTP ustawionym w kluczu status jego danych, na przykład 400 przy błędnych danych wejściowych.
• Gdy opakowujesz istniejący callback, przepuść zwracaną wartość przez rest_ensure_response().

<?php
declare(strict_types=1);

class Wppoland_Metrics_Controller extends WP_REST_Controller
{
    protected $namespace = 'wppoland/v1';
    protected $rest_base = 'metrics';

    public function register_routes(): void
    {
        register_rest_route($this->namespace, '/' . $this->rest_base . '/(?P<id>\d+)', [
            [
                'methods' => WP_REST_Server::READABLE,
                'callback' => [$this, 'get_item'],
                'permission_callback' => '__return_true',
                'args' => [
                    'id' => ['type' => 'integer', 'required' => true],
                ],
            ],
            'schema' => [$this, 'get_public_item_schema'],
        ]);
    }

    public function get_item($request)
    {
        $post = get_post((int) $request['id']);
        if (!$post || $post->post_status !== 'publish') {
            return new WP_Error('rest_post_invalid_id', __('Not found.', 'wppoland'), ['status' => 404]);
        }
        return rest_ensure_response([
            'id' => $post->ID,
            'title' => get_the_title($post),
        ]);
    }

    public function get_item_schema(): array
    {
        return [
            '$schema' => 'http://json-schema.org/draft-04/schema#',
            'title' => 'wppoland_metrics',
            'type' => 'object',
            'properties' => [
                'id' => ['type' => 'integer'],
                'title' => ['type' => 'string'],
            ],
        ];
    }
}

add_action('rest_api_init', function (): void {
    (new Wppoland_Metrics_Controller())->register_routes();
});

Właściwości są zadeklarowane bez typu celowo: WP_REST_Controller deklaruje $namespace i $rest_base bez typu, a PHP nie pozwala na typowaną redeklarację w klasie potomnej. Pełne omówienie kontrolera znajdziesz w naszym przewodniku po własnych endpointach REST API.

#6. Czy GraphQL jest szybszy niż REST API w WordPressie

W 2026 roku wydajność API mierzy się efektywnością: liczbą żądań, rozmiarem odpowiedzi i kosztem po stronie serwera.

• Opóźnienia sieciowe: na złożonych stronach wygrywa GraphQL. Łącząc wiele danych w jedno żądanie, eliminuje kolejne cykle sieciowe, których potrzebuje strona w REST z wpisem, autorem, terminami i powiązanymi wpisami.
• Strategia cachowania: REST wygrywa łatwością użycia. Ponieważ każdy endpoint to unikalny adres URL, możesz go niewielkim wysiłkiem zacachować globalnie na Cloudflare. GraphQL potrzebuje żądań GET albo persisted queries, żeby osiągnąć podobne wyniki cachowania na brzegu sieci.
• CPU serwera: przy jednym prostym zasobie REST jest zwykle lżejsze. GraphQL musi sparsować i zwalidować dokument zapytania, zanim cokolwiek rozwiąże, dlatego object cache ma na stronie z GraphQL większe znaczenie.

Zespół WPGraphQL opublikował jeden pomiar: pobranie 100 wpisów zajęło 335 kb i 7,91 s z endpointu REST wobec 6,4 kb i 67 ms z WPGraphQL (WPGraphQL vs WP REST API). Traktuj to jako test samego dostawcy na domyślnej odpowiedzi REST. Żądanie REST z _fields zamyka dużą część różnicy w rozmiarze odpowiedzi, więc zmierz własne strony, zanim podejmiesz decyzję tylko na podstawie tego argumentu.

#7. Jak cachować GraphQL w CDN dzięki persisted queries

Zapytania GraphQL wysyła się zwykle jako HTTP POST z zapytaniem w treści żądania, a CDN nie cachuje POST po adresie URL. Według wytycznych WPGraphQL typową metodą jest POST, a GET ma ograniczone wsparcie (Interacting with WPGraphQL). Cachowaniem na brzegu sieci zajmuje się wtyczka towarzysząca WPGraphQL Smart Cache (wersja 2.3.3, ponad 6000 aktywnych instalacji, obecnie część monorepo WPGraphQL, według jej strony w katalogu).

Jak to działa według dokumentacji Smart Cache:

• Cache sieciowy: żeby z niego skorzystać, wysyłasz żądania HTTP GET o dane publiczne. Odpowiedzi niosą nagłówek X-GraphQL-Keys z tagami wszystkiego, czego dotknęło zapytanie. Gdy treść się zmienia, Smart Cache wysyła zdarzenia czyszczenia, a host usuwa z cache dokumenty oznaczone tymi kluczami. Przewodnik wymienia WP Engine i Pantheon jako hosty, które to obsługują. Domyślny max-age to 600 sekund, do zmiany w ustawieniach Cache wtyczki (Network cache).
• Persisted queries: dokument zapytania jest przechowywany na serwerze w niepublicznym typie wpisu graphql_document i wskazywany przez identyfikator zapytania. Slug dokumentu to hash SHA-256 zapytania, a klient może zarejestrować nowy queryId tylko wtedy, gdy zgadza się on z tym hashem. Klienci wysyłają potem krótkie żądania GET, na przykład ?queryId=getPostById&variables={...}. Wtyczka współpracuje z Apollo Persisted Query Link (Persisted queries).
• Listy dozwolonych i zablokowanych zapytań: w ustawieniach zapisanych zapytań wybierasz między w pełni publicznym endpointem, dopuszczeniem tylko wybranych zapisanych zapytań albo zablokowaniem wybranych. Użytkownicy z uprawnieniem manage_options są z tego wyłączeni.

Gdy działają żądania GET, persisted queries i czyszczenie po tagach, odpowiedź GraphQL trafia do cache na brzegu sieci podobnie jak adres URL w REST. Bez nich cachowanie GraphQL sprowadza się do object cache WordPressa.

#8. WordPress REST batch API a batching w GraphQL

WordPress 5.6 dodał framework batch pod adresem /wp-json/batch/v1. Przyjmuje jedno żądanie POST z kilkoma podżądaniami, domyślnie 25 (filtr rest_get_max_batch_size). Żądania GET nie są obsługiwane, więc framework służy do zapisu, a każda trasa musi się na niego zgodzić przez allow_batch przy rejestracji. Tryb require-all-validate odrzuca całą paczkę, jeśli którekolwiek żądanie nie przejdzie walidacji (REST API batch framework in WordPress 5.6).

#Ograniczenia batchingu w REST API

1. Brak składania danych: podżądania działają jako osobne operacje. Nie przekażesz wyniku żądania A (identyfikatora autora) do żądania B w tej samej paczce.
2. Nastawienie na zapis: bez GET endpoint batch w ogóle nie pomaga frontendowi, który głównie czyta.
3. Brak cachowania na brzegu: to POST, więc CDN przepuszcza każdą paczkę do serwera źródłowego.

GraphQL z założenia rozwiązuje powiązane dane w jednym zapytaniu, a WPGraphQL przyjmuje też zapytania wsadowe. Jego dokumentacja bezpieczeństwa zaznacza, że zapytania wsadowe możesz ograniczyć albo wyłączyć na stronie ustawień GraphQL.

#9. Limity paginacji w REST i GraphQL

REST API ogranicza per_page do 100 rekordów i przy każdej kolekcji zwraca dwa nagłówki: X-WP-Total (łączna liczba rekordów) i X-WP-TotalPages (łączna liczba stron) (Pagination). Klient, który potrzebuje 450 wpisów, wysyła pięć żądań.

WPGraphQL używa połączeń opartych na kursorach (first, after, pageInfo { hasNextPage endCursor }). Dla większości połączeń ogranicza liczbę elementów na stronę połączenia do 100, a filtr graphql_connection_max_query_amount zmienia ten limit (WPGraphQL security). Podnoś go tylko razem z limitem głębokości i cachowaniem, bo przy większych stronach wysłanie kosztownego zapytania kosztuje mniej.

#10. Uwierzytelnianie w WordPress REST API i WPGraphQL

REST API ma dwie wbudowane metody (Authentication):

• Uwierzytelnianie ciasteczkami dla kodu działającego w zalogowanym kokpicie. Ręczne żądanie musi wysłać nonce dla akcji wp_rest, zwykle w nagłówku X-WP-Nonce. Bez nonce żądanie jest traktowane jako nieuwierzytelnione, nawet jeśli użytkownik jest zalogowany.
• Application Passwords, w rdzeniu od WordPressa 5.6. Korzystają z Basic Auth i działają tylko przez HTTPS.

WPGraphQL trzyma się uprawnień WordPressa: wszystko, co WordPress udostępnia publicznie, jest publiczne w GraphQL, a dane wymagające uwierzytelnienia w WordPressie wymagają uwierzytelnionego żądania GraphQL. Użytkownicy bez opublikowanych wpisów są wyłączeni z publicznych zapytań o użytkowników, a pola takie jak adres e-mail użytkownika wymagają określonego uprawnienia (WPGraphQL security). Logowanie oparte na tokenach (JWT i podobne) pochodzi z rozszerzeń, nie z samej wtyczki.

#11. Jak zabezpieczyć REST API i GraphQL w WordPressie

Źródła: WPGraphQL security, REST API Handbook FAQ. Handbook blokuje anonimowy dostęp do REST sprawdzeniem is_user_logged_in() na filtrze rest_authentication_errors. Ograniczanie liczby żądań (rate limiting) należy dla obu API do warstwy brzegowej (WAF albo CDN), bo nie dostarcza go ani wtyczka, ani rdzeń.

#12. Generowanie typów TypeScript z WPGraphQL

Ponieważ schemat GraphQL jest typowany i dostępny przez introspection, narzędzia takie jak GraphQL Code Generator mogą odczytać schemat oraz zapytania frontendu i wygenerować typy TypeScript dla wyniku każdego zapytania. Pole, które stanie się nullable albo zniknie ze schematu, nie przejdzie wtedy sprawdzania typów w edytorze i w CI, zanim trafi na produkcję.

import type { TypedDocumentNode } from '@graphql-typed-document-node/core';
import { print } from 'graphql';

export async function executeGraphQL<TData, TVariables>(
  document: TypedDocumentNode<TData, TVariables>,
  variables?: TVariables
): Promise<TData> {
  const response = await fetch(import.meta.env.WP_GRAPHQL_ENDPOINT, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query: print(document), variables }),
  });
  if (!response.ok) throw new Error(`GraphQL HTTP ${response.status}`);
  const { data, errors } = await response.json();
  if (errors?.length) throw new Error(errors[0].message);
  return data;
}

REST API publikuje JSON Schema dla każdej trasy, więc i tam można generować typy, ale składasz je endpoint po endpoincie, a serwer nie waliduje pól wybranych przez Twojego klienta.

#13. Obsługa błędów w REST API i GraphQL

Błąd REST to WP_Error zserializowany do JSON-a z polami code, message i data.status, a status HTTP odpowiedzi odpowiada data.status. Gdy żądanie się nie powiedzie, cała odpowiedź jest błędem. To przewidywalne dla monitoringu, ale strona zbudowana z jednego wywołania REST nie wyrenderuje połowy swoich danych.

GraphQL potrafi zwrócić dane częściowe. Odpowiedź zawiera jednocześnie data i errors, a każdy błąd ma path, który wskazuje pole, które zawiodło:

{
  "data": { "post": { "title": "Headless WordPress architecture", "relatedPosts": null } },
  "errors": [
    { "message": "Internal server error", "path": ["post", "relatedPosts"] }
  ]
}

Frontend może wyrenderować artykuł i pokazać zastępczą treść tylko w bloku, który zawiódł. Druga strona medalu: żądanie GraphQL, które częściowo się nie powiodło, nadal zwraca HTTP 200, więc monitoring musi czytać tablicę errors, a nie tylko kody statusu.

#14. Mutacje GraphQL i optimistic UI w WordPressie

Zapis w GraphQL to mutacje. Mutacja zmienia dane i w tej samej odpowiedzi zwraca zaktualizowany obiekt, więc klient może odświeżyć lokalny stan bez drugiego żądania. Rdzeń WPGraphQL ma mutacje dla wpisów, terminów, użytkowników i komentarzy, na przykład createComment:

mutation AddComment($input: CreateCommentInput!) {
  createComment(input: $input) {
    success
    comment { id content date }
  }
}

To upraszcza optimistic UI: interfejs od razu pokazuje nowy komentarz i wycofuje go tylko wtedy, gdy mutacja zwróci błąd. Mutacje koszyka WooCommerce nie są częścią rdzenia WPGraphQL, pochodzą z osobnego rozszerzenia. W REST ten sam przepływ to POST, a potem odczyt zwróconego zasobu, co przy pojedynczych zapisach działa równie dobrze.

#15. GraphQL czy REST dla agentów AI i Abilities API

Agenci AI i klienci MCP są dziś zwykłymi odbiorcami API. Introspection w GraphQL pozwala agentowi odczytać schemat i zobaczyć, jakie typy i argumenty istnieją, ale WPGraphQL domyślnie wyłącza publiczną introspection, więc agent potrzebuje uwierzytelnionego dostępu albo wyeksportowanego schematu.

Rdzeń WordPressa poszedł inną drogą. Abilities API, w rdzeniu od WordPressa 6.9 (2 grudnia 2025), rejestruje operacje ze schematem wejścia i wyjścia, callbackiem uprawnień i callbackiem wykonania, a udostępnia je przez endpointy REST wp-abilities/v1 i MCP Adapter (Abilities API in WordPress 6.9). Dla agentów, które działają na stronie, ta warstwa oparta na REST jest natywną ścieżką. Więcej w naszym przewodniku po WordPress Abilities API.

#16. Testowanie API WordPressa w GraphiQL i Postmanie

• REST: znany niemal każdemu deweloperowi. Endpointy przetestujesz od razu w przeglądarce albo w narzędziach takich jak Postman. Dodaj ?_envelope, gdy klient nie potrafi czytać nagłówków: odpowiedź niesie wtedy nagłówki i kod statusu w treści.
• GraphQL: WPGraphQL dostarcza GraphiQL, IDE działające w przeglądarce w panelu WordPressa, które pozwala przeglądać cały schemat, widzieć dostępne pola i testować zapytania oraz mutacje z autouzupełnianiem. Dla zespołów frontendowych to realny wzrost produktywności.

Żeby chronić się przed regresjami, porównuj w CI zapytania frontendu ze schematem przy każdym merge’u, tak żeby usunięte albo zmienione pole przerwało build. Po stronie REST waliduj odpowiedzi względem JSON Schema każdej trasy.

#17. Jak przejść z REST API na WPGraphQL bez przestoju

1. Współistnienie: zainstaluj WPGraphQL na stagingu poleceniem wp plugin install wp-graphql --activate i zmapuj do schematu każdy własny typ wpisu i taksonomię. REST nadal obsługuje produkcję.
2. Najpierw strony tylko do odczytu: przenieś archiwa i listy na zapytania GraphQL z wygenerowanymi typami, a potem porównaj rozmiar odpowiedzi i czas odpowiedzi z wersją REST.
3. Strony szczegółów i cachowanie: przenieś widoki pojedynczych wpisów, a potem dodaj Smart Cache z żądaniami GET albo persisted queries, jeśli Twój hosting obsługuje cache sieciowy.
4. Uporządkuj ekspozycję REST: zostaw trasy REST, z których korzystają webhooki, automatyzacje i integracje, a tam, gdzie nie został żaden publiczny odbiorca, wymagaj uwierzytelnienia.

#18. Porównanie REST API i GraphQL w tabeli

#Kiedy wybrać GraphQL zamiast REST API w WordPressie

Jeśli budujesz nowoczesną stronę decoupled w React, Astro lub Next.js, GraphQL zwykle pasuje lepiej. Możliwość żądania dokładnie tego, co jest potrzebne, razem z wygenerowanymi typami, przekłada się na lżejszy i łatwiejszy w utrzymaniu frontend.

Nie ignoruj jednak REST. Dla prostych integracji, aplikacji mobilnych potrzebujących tylko listy wpisów, wewnętrznej automatyzacji, webhooków i agentów AI korzystających z Abilities API natywne REST API pozostaje najszybszym sposobem na wykonanie zadania, bez wtyczki do utrzymywania. Wiele produkcyjnych stron używa obu: GraphQL dla publicznego frontendu, REST dla integracji.

Więcej o migracji strony na Astro i Next.js w WPPoland.

Czy wciąż pobierasz cały obiekt wpisu tylko dla tytułu? Dodaj _fields jeszcze dziś, a przejście na GraphQL zaplanuj wtedy, gdy frontend z tego wyrośnie.