Wtyczka Enhanced WP REST API

Rozszerzone WordPress REST API

Stworzyłem wtyczkę open-source, która rozszerza REST API WordPressa dla architektur headless CMS. Dzięki wtyczce wbudowane REST API WordPressa zyskuje funkcje niezbędne do efektywnej współpracy z nowoczesnymi frameworkami frontendowymi jak Astro, Next.js czy Nuxt.

Problem

Domyślne REST API WordPressa zapewnia podstawową funkcjonalność, ale brakuje mu kluczowych funkcji dla wdrożeń produkcyjnych w architekturze headless:

• Niekompletne struktury danych wymagające wielu zapytań API
• Pełne URL-e powodujące problemy między środowiskami (dev, staging, produkcja)
• Brak wbudowanej integracji analitycznej dla popularnych postów
• Ograniczone wsparcie wielojęzyczności
• Brak przekierowań w trybie headless
• Brak niestandardowego sortowania taksonomii

Wtyczka rozwiązuje te problemy zestawem ulepszeń opartych na doświadczeniach z rzeczywistych projektów headless WordPress.

Kluczowe funkcje

Rozszerzona struktura danych

Wtyczka wzbogaca standardowe odpowiedzi REST API o dodatkowe pola potrzebne aplikacjom frontendowym:

Rozszerzone dane autora - Kompletne informacje o autorze zawierające ID, nazwę, nicename, URL avatara, opis i względne linki do strony autora w jednej odpowiedzi. Nie ma potrzeby osobnych zapytań do endpointu /users.

Wiele rozmiarów obrazów - Pole featured_image_urls dostarcza wszystkie zarejestrowane rozmiary obrazów WordPress (thumbnail, medium, large, full), eliminując potrzebę dodatkowych zapytań API do pobierania różnych wymiarów dla responsywnych obrazów.

Szacowany czas czytania - Automatyczne obliczanie szacowanego czasu czytania na podstawie długości treści (np. “5 min czytania”), przydatne dla szablonów blogowych i poprawy doświadczenia użytkownika.

Bogate informacje o taksonomiach - Rozszerzone dane kategorii i tagów z opisami, liczbą postów, ID kategorii nadrzędnych i względnymi URL-ami w głównej odpowiedzi posta.

URL-e niezależne od środowiska

Wszystkie URL-e w odpowiedziach API są konwertowane na ścieżki względne (np. /blog/nazwa-posta/ zamiast https://example.com/blog/nazwa-posta/). Dotyczy to:

• Permalinków postów
• URL-i stron autorów
• URL-i archiwów kategorii i tagów
• URL-i obrazów wyróżniających
• URL-i tłumaczeń (gdy Polylang jest aktywny)

Korzyści:

• Spójne zachowanie między środowiskami deweloperskim, stagingowym i produkcyjnym
• Bez konieczności konfiguracji zależnej od środowiska czy operacji znajdź-zamień
• Uproszczone wdrożenia i testowanie
• Frontend może konstruować pełne URL-e z własną domeną

Integracja z Polylang

Płynne wsparcie wielojęzyczności gdy wtyczka Polylang jest aktywna:

Dane tłumaczeń - Pole translations_data udostępnia wszystkie dostępne tłumaczenia dla postów, kategorii i tagów z kompletnymi informacjami:

• Tłumaczenia postów zawierają ID, tytuł, slug, excerpt, status, ID obrazu wyróżniającego i względny link
• Tłumaczenia kategorii/tagów zawierają ID, nazwę, slug i względny link
• Idealne do tworzenia przełączników języków w aplikacjach headless
• Kluczowe dla SEO - umożliwia prawidłową implementację tagów hreflang w Astro i innych frameworkach frontendowych, co wcześniej było trudne do zrealizowania bez tych danych w odpowiedzi REST API

Dostępne języki - Lista wszystkich języków strony w polu available_languages

Filtrowanie językowe - Automatyczne zapytania API uwzględniające język respektują aktualny kontekst językowy

Dlaczego to ma znaczenie dla SEO: Bez pola translations_data implementacja prawidłowych tagów hreflang w architekturze headless wymagałaby dodatkowych zapytań API dla każdego tłumaczenia, co jest niepraktyczne dla generowania stron statycznych. Ta wtyczka rozwiązuje ten problem dostarczając wszystkie URL-e tłumaczeń w jednej odpowiedzi, umożliwiając wyszukiwarkom prawidłową identyfikację wariantów językowych i serwowanie odpowiedniej treści użytkownikom.

Integracja z Google Analytics 4

Pobieranie popularnych postów na podstawie rzeczywistych danych o odsłonach z Google Analytics 4 zamiast prostych liczników wyświetleń:

Funkcje:

• Posty sortowane według rzeczywistych odsłon z GA4
• Konfigurowalne okresy czasowe: 7, 14, 30 lub 90 dni
• Filtrowanie językowe dla stron wielojęzycznych (integracja z Polylang)
• Inteligentne cachowanie z konfigurowalnym czasem trwania (1-24 godziny)
• Uwierzytelnianie JWT konta serwisowego
• Nie wymaga Google SDK - lekka implementacja wykorzystująca WordPress HTTP API

Endpoint API:

/wp-json/wp/v2/posts/popular?limit=6&period=7d&lang=pl

Odpowiedź zawiera:

• Dane posta ze wszystkimi rozszerzonymi polami
• Liczbę odsłon dla każdego posta
• Status cache i znacznik czasu
• Łączną liczbę wyników i informacje o okresie

Umożliwia to dynamiczne sekcje “popularne posty” oparte na rzeczywistym zachowaniu użytkowników, idealne do zwiększania zaangażowania i odkrywania treści.

Tryb headless

Opcjonalna funkcja przekierowania frontendu dla w pełni headless WordPress:

Jak to działa:

• Przekierowania 301 wysyłają wszystkich odwiedzających frontend do Twojej aplikacji headless
• Oryginalne ścieżki URL są zachowane dla SEO (np. /blog/slug-posta → https://frontend.com/blog/slug-posta)
• Panel administracyjny pozostaje dostępny dla autoryzowanych użytkowników (uprawnienie edit_posts)
• REST API, GraphQL, WP-CLI i CRON działają normalnie

Korzyści:

• Utrzymanie WordPressa jako czystego backendu/CMS
• Zapobieganie problemom z duplikacją treści
• Prawidłowe przekierowania przyjazne SEO
• Brak potrzeby osobnych wtyczek trybu headless

Niestandardowe sortowanie taksonomii

Wsparcie dla sortowania kategorii i tagów przez parametr term_order:

/wp-json/wp/v2/categories?orderby=term_order
/wp-json/wp/v2/tags?orderby=term_order

Respektuje ręczne sortowanie taksonomii z wtyczek, zapewniając spójną nawigację między panelem administracyjnym WordPress a headless frontendem. Kategorie domyślnie sortowane rosnąco.

Rozszerzenie API komentarzy

Opcjonalna konfiguracja REST API dla anonimowego komentowania:

• Pozwala na przesyłanie komentarzy bez uwierzytelnienia przez REST API
• Konfigurowalne powiadomienia email dla moderatorów o nowych komentarzach
• Idealne dla formularzy kontaktowych Jamstack i systemów komentarzy headless
• Wszystko konfigurowane przez panel administracyjny WordPress

Przykład kodu

// Pobieranie postów ze wszystkimi rozszerzonymi danymi
fetch('/wp-json/wp/v2/posts')
  .then(res => res.json())
  .then(posts => {
    const post = posts[0];

    // Względne URL-e gotowe dla frontendu
    console.log(post.relative_link);        // "/blog/tytul-posta"
    console.log(post.author_data.url);      // "/author/jan-kowalski"

    // Kompletne dane autora w jednej odpowiedzi
    console.log(post.author_data);
    // {
    //   id: 1,
    //   name: "Jan Kowalski",
    //   nicename: "jan-kowalski",
    //   avatar: "/path/to/avatar.jpg",
    //   description: "Bio autora...",
    //   url: "/author/jan-kowalski"
    // }

    // Wszystkie rozmiary obrazów dostępne
    console.log(post.featured_image_urls);
    // {
    //   thumbnail: "/uploads/image-150x150.jpg",
    //   medium: "/uploads/image-300x200.jpg",
    //   large: "/uploads/image-1024x768.jpg",
    //   full: "/uploads/image.jpg"
    // }

    // Szacowany czas czytania
    console.log(post.read_time); // "5 min czytania"

    // Dane wielojęzyczne (gdy Polylang aktywny)
    console.log(post.translations_data);
    console.log(post.available_languages); // ["en", "pl"]
  });

Zastosowanie w praktyce

Wtyczka powstała na potrzeby bloga polo.blue i jest tam aktywnie wykorzystywana. To wielojęzyczny blog motoryzacyjny zbudowany na frontendzie Astro z WordPressem jako headless backend.

Implementacja polo.blue:

• Backend WordPress - Zarządzanie treścią z Polylang dla tłumaczeń polsko/angielskich
• Frontend Astro - Generowanie stron statycznych korzystające z rozszerzonego REST API
• Integracja GA4 - Sekcje popularnych postów oparte na rzeczywistych danych o odsłonach
• Względne URL-e - Płynne wdrożenia między wieloma środowiskami
• Tryb headless - Kompletna separacja frontendu z przekierowaniami 301

Wtyczka nadaje się również do innych implementacji headless WordPress:

• Wielojęzyczne blogi z nowoczesnymi frameworkami frontendowymi
• Strony z treściami i sekcjami trendów opartymi na GA4
• Strony marketingowe z backendem WordPress i prezentacją Next.js/Nuxt
• Zarządzanie treścią e-commerce z niestandardowymi taksonomiami

Wtyczka jest aktywnie rozwijana i przetestowana w środowiskach produkcyjnych.

Masz własnego WordPressa, który wymaga opieki, przyspieszenia lub migracji na headless? Zobacz pakiety naprawy i opieki WordPress — od 450 zł za awaryjną naprawę do migracji na headless od 3 900 zł.

Wykorzystane technologie

Wtyczka jest open-source (GPL v2 lub nowsza) i dostępna na GitHubie - zapraszam do współtworzenia. Wszystkie funkcje są opcjonalne i indywidualnie konfigurowalne przez panel administracyjny WordPress.