# Wtyczka Enhanced WP REST API
> Wtyczka open-source rozszerzająca WordPress REST API dla architektur headless CMS. Oferuje integrację z GA4, dane tłumaczeń Polylang do prawidłowej implementacji hreflang SEO, względne URL-e oraz tryb headless z przekierowaniami 301.
- URL: https://spoko.space/pl/enhanced-wp-rest-api/
- Published: 2025-08-20
- Tags: wordpress, rest-api, headless-cms, php, open-source, polylang, ga4, astro
---## 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](https://polylang.pro/) 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

```javascript
// 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](https://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.

## 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.