WordPress REST API

WordPress REST API je jednou z technologií, které používám v případech, kdy WordPress potřebuje komunikovat s externími aplikacemi, poskytovat strukturovaná data rozhraním v JavaScriptu nebo zpřístupňovat vlastní aplikační funkcionalitu nad rámec běžného vykreslování stránek.

Používám ji k tomu, aby WordPress fungoval jako strukturovaný backend schopný vyměňovat data ve formátu JSON s dalšími systémy.

Může jít o vestavěný obsah WordPressu, vlastní typy příspěvků, taxonomie, metadata i zcela vlastní aplikační endpointy.

WordPress REST API pro mě není jen způsob, jak načítat příspěvky.

Je to jeden z hlavních nástrojů pro propojení WordPressu s širším softwarovým ekosystémem.

Jak WordPress REST API používám

WordPress REST API používám například pro:

• programové načítání obsahu z WordPressu,
• zpřístupňování vlastních typů příspěvků,
• práci s taxonomiemi,
• propojování JavaScriptových aplikací s WordPressem,
• integraci externích nástrojů,
• vytváření vlastních endpointů,
• vzdálené aktualizace obsahu WordPressu,
• zpřístupňování strukturovaných metadat,
• automatizaci,
• headless architektury,
• integraci mobilních nebo desktopových aplikací.

Konkrétní implementace závisí na tom, zda WordPress v daném projektu funguje především jako web, redakční systém nebo aplikační backend.

WordPress jako strukturovaný backend

Tradiční WordPress vykresluje kompletní HTML stránky na serveru.

REST API nabízí jiný způsob práce se stejným zdrojovým obsahem.

Místo požadavku na hotovou vykreslenou stránku může aplikace požadovat strukturovaná data ve formátu JSON.

Koncepčně:

WordPress
↓
REST API
↓
JSON
↓
Webový / mobilní / automatizační klient

Tím se odděluje datová vrstva od prezentační vrstvy.

Stejný obsah WordPressu tak může využívat více různých rozhraní.

Vestavěné endpointy

WordPress zpřístupňuje REST endpointy pro řadu svých vestavěných zdrojů.

Patří mezi ně například:

• příspěvky,
• stránky,
• kategorie,
• štítky,
• média,
• uživatelé,
• komentáře,
• taxonomie.

Požadavek například na:

/wp-json/wp/v2/posts

může vrátit strukturovaná data příspěvků ve formátu JSON.

Vestavěné API je užitečné samo o sobě, ale u projektů s vlastními datovými modely jej často rozšiřuji.

Vlastní typy příspěvků

WordPress často používám s vlastními typy příspěvků.

Pokud to dává smysl, lze tyto typy příspěvků zpřístupnit také prostřednictvím REST API.

Web může například obsahovat entity reprezentující:

• aplikace,
• technologie,
• projekty,
• vozidla,
• lokality,
• produkty.

Místo toho, aby se s těmito entitami zacházelo jako s běžnými stránkami, může je WordPress reprezentovat jako strukturované typy obsahu a REST API je může zpřístupnit externím klientům.

Výsledkem je výrazně čistší datový model.

Vlastní taxonomie

Součástí architektur WordPressu založených na API mohou být také vlastní taxonomie.

Používám je tam, kde entity potřebují strukturovanou klasifikaci, například podle:

• kategorií,
• technologií,
• regionů,
• typů,
• stavů.

Externí aplikace pak mohou tyto klasifikace programově načítat a pracovat s nimi.

To je užitečné zejména pro filtry, vyhledávací rozhraní a synchronizaci dat.

Advanced Custom Fields

WordPress REST API často kombinuji s Advanced Custom Fields.

ACF poskytuje strukturovaná metadata.

REST API umožňuje tato strukturovaná data zpřístupnit dalším systémům.

Vlastní typ příspěvku může například obsahovat pole:

title
short_description
status
technology
external_url
related_projects

Odpověď API pak může tato data poskytovat v předvídatelné struktuře.

To je výrazně praktičtější než nutit externí aplikaci, aby informace získávala z již vykresleného HTML.

Vlastní endpointy

Pokud standardní endpointy WordPressu nereprezentují požadované chování aplikace, vytvářím vlastní REST endpointy.

Vlastní endpoint může poskytovat například:

• specializované dotazy,
• aplikační akce,
• agregovaná data,
• integraci externích systémů,
• vlastní vyhledávání,
• spouštění automatizací.

Například:

/wp-json/myapp/v1/status

nebo:

/wp-json/myapp/v1/projects

Endpoint tak může vracet přesně takovou strukturu, jakou klient potřebuje.

Namespace

Pro vlastní REST routy používám namespace.

Například:

myapp/v1

Tím se zabrání konfliktům vlastní funkcionality s:

• jádrem WordPressu,
• pluginy,
• dalšími aplikačními endpointy.

Verzované namespace navíc umožňují API v budoucnu měnit bez toho, aby se okamžitě rozbili existující klienti.

Registrace rout

Vlastní endpointy se registrují explicitně.

Ve WordPressu se to obvykle provádí pomocí register_rest_route().

Definice routy může určovat:

• HTTP metody,
• callback,
• permission callback,
• přijímané argumenty.

Tyto odpovědnosti udržuji explicitní namísto vytváření jednoho generického endpointu, který provádí nesouvisející operace.

HTTP metody

HTTP metody používám podle typu prováděné operace.

Typické použití:

• GET pro načítání informací,
• POST pro vytváření nebo spouštění operací,
• PUT nebo PATCH pro aktualizace,
• DELETE pro odstraňování.

Endpoint by měl svůj účel komunikovat jednoznačně.

Operace pro čtení by neměly neočekávaně měnit stav aplikace.

Permission callbacky

Permission callbacky patří mezi nejdůležitější části vlastních WordPress REST endpointů.

Routa by měla explicitně definovat, kdo ji smí používat.

Podle projektu mohou oprávnění vycházet z:

• WordPress capabilities,
• stavu přihlášeného uživatele,
• aplikačně specifické autorizace.

Nikdy nepředpokládám, že endpoint je soukromý jen proto, že není viditelný v uživatelském rozhraní.

Autorizace patří na server.

Veřejná a soukromá data

WordPress může prostřednictvím REST API anonymně zpřístupňovat veřejný obsah.

Soukromé nebo administrativní informace vyžadují odlišný přístup.

Pečlivě rozlišuji mezi:

• daty určenými pro veřejné použití,
• daty autentizované aplikace,
• administrativní funkcionalitou.

REST endpoint nesmí zpřístupnit citlivé informace jen proto, že se daná data nacházejí ve WordPressu.

Autentizace

Autentizované REST operace vyžadují vhodný mechanismus autentizace.

U požadavků prováděných z přihlášené relace WordPressu může WordPress využít existující autentizaci pomocí cookies společně s ochranou prostřednictvím nonce.

Pro externí aplikace WordPress podporuje také Application Passwords pro autentizovaný přístup k API přes HTTPS.

Správný způsob autentizace závisí na typu klienta a architektuře nasazení.

Application Passwords

Application Passwords jsou užitečné tehdy, když externí aplikace potřebuje autentizovaný přístup k WordPressu bez použití běžného hesla uživatele.

Umožňují vytvořit přihlašovací údaje určené přímo pro přístup aplikace.

Považuji je za citlivé údaje.

Neměly by být:

• vystavené ve frontendovém JavaScriptu,
• uložené do verzovacího systému,
• součástí veřejné konfigurace,
• zapisované do logů.

Pokud musí přihlašovací údaje zůstat důvěrné, integrace patří do kontrolovaného backendového prostředí.

Nonces

U REST požadavků pocházejících z autentizovaných rozhraní WordPressu poskytují nonces ochranu proti cross-site request forgery.

Používám bezpečnostní mechanismy WordPressu odpovídající danému kontextu a zbytečně nevymýšlím vlastní tokeny.

Nonces nenahrazují oprávnění uživatele.

Je potřeba řešit jak legitimitu požadavku, tak autorizaci.

WordPress capabilities

U autentizovaných endpointů používám WordPress capabilities, pokud odpovídají oprávňovacímu modelu aplikace.

Místo pouhé kontroly, zda je uživatel přihlášený, může endpoint ověřit, zda má skutečně oprávnění požadovanou operaci provést.

Může jít například o oprávnění k:

• úpravě obsahu,
• publikování,
• správě aplikačně specifických zdrojů.

REST autorizace tak zůstává v souladu se zbytkem WordPressu.

Validace vstupu

Vlastní endpointy mohou přijímat libovolná externí data.

Parametry požadavků proto před použitím validuji.

Podle endpointu může validace zahrnovat:

• povinná pole,
• očekávané datové typy,
• povolené hodnoty,
• identifikátory,
• délku řetězců,
• číselné rozsahy.

API by mělo neplatné požadavky odmítnout ještě předtím, než se dostanou do aplikační logiky.

Sanitizace

Validace odpovídá na otázku:

„Je tato hodnota přijatelná?“

Sanitizace odpovídá na otázku:

„Jak má být tato přijatá hodnota normalizována?“

Pro data, jako jsou:

• prostý text,
• URL,
• e-mailové adresy,
• celá čísla,

používám odpovídající sanitizační funkce WordPressu.

Nespoléhám na jednu univerzální sanitizační funkci pro všechny typy vstupu.

Escaping

Sanitizace vstupu a escapování výstupu řeší odlišné problémy.

Pokud se data z API později vykreslují do HTML, musí být stále správně escapována podle konkrétního výstupního kontextu.

Tyto odpovědnosti udržuji oddělené.

REST API poskytuje strukturovaná data.

Vrstva zodpovědná za vykreslení je nadále odpovědná za jejich bezpečné zobrazení.

JSON odpovědi

WordPress REST API komunikuje prostřednictvím JSON.

Preferuji předvídatelné struktury odpovědí.

U vlastního endpointu může struktura například vypadat takto:

{
  "id": 42,
  "title": "Example",
  "status": "active"
}

U chyb preferuji konzistentní aplikační chybové kódy a smysluplné HTTP stavové kódy.

Externí klienti by neměli být nuceni analyzovat libovolné textové řetězce jen proto, aby zjistili, co se stalo.

REST response objekty

WordPress poskytuje mechanismy REST odpovědí, které endpointům umožňují vracet strukturovaná data společně s odpovídajícím HTTP chováním.

Používám nativní mechanismy WordPressu pro odpovědi a zpracování chyb namísto ručního vypisování JSON a ukončování běhu PHP.

Vlastní endpointy tak zůstávají integrovány do standardní REST infrastruktury.

Zpracování chyb

Vlastní endpoint potřebuje předvídatelné chování při selhání.

Možné situace zahrnují:

• neplatné parametry,
• chybějící zdroj,
• nedostatečné oprávnění,
• selhání autentizace,
• interní chybu při zpracování.

Endpoint by měl tyto stavy jednoznačně komunikovat prostřednictvím:

• odpovídajících stavových kódů,
• strukturovaných chybových dat.

Integrace se díky tomu výrazně snáze ladí.

Query parametry

Query parametry používám v případech, kdy klient potřebuje řídit způsob načítání dat.

Například:

?status=active
?page=2
?per_page=20

Vlastní parametry vždy explicitně validuji.

Libovolné parametry z požadavku nepředávám přímo do databázových nebo WordPress query argumentů bez kontroly toho, které hodnoty jsou povolené.

Stránkování

Velké kolekce by se neměly automaticky vracet v jedné obrovské odpovědi.

Pokud může API zpřístupňovat velké množství záznamů, používám stránkování.

To zlepšuje:

• dobu odezvy,
• využití paměti,
• objem přenášených dat,
• výkon klienta.

WordPress už nabízí vzory stránkování pro řadu vestavěných kolekčních endpointů.

Filtrování

Vlastní aplikace často potřebují filtrovaná data.

Například:

/projects?technology=python

nebo:

/projects?status=published

Zpřístupňuji filtry, které odpovídají skutečným konceptům aplikace, namísto toho, abych klientům umožňoval neomezený přístup k interním parametrům dotazů.

Veřejné API tak zůstává stabilní i v případě, že se interní implementace změní.

Výkon

REST endpointy mohou být náročné, pokud při každém požadavku provádějí neefektivní WordPress dotazy.

Sleduji zejména:

• počet dotazů,
• dotazy na metadata,
• dotazy na taxonomie,
• velikost vraceného payloadu,
• opakované výpočty.

U náročných výsledků, které se často nemění, může být vhodné cachování.

API by se nemělo stát pohodlným způsobem, jak vytvořit neefektivní backend.

Omezení nadměrně velkých odpovědí

Vrácení každého dostupného pole není vždy užitečné.

Velké odpovědi API zvyšují:

• objem přenášených dat,
• čas potřebný k parsování,
• spotřebu paměti.

U vlastních endpointů preferuji vracet pouze informace, které klient skutečně potřebuje.

Tím se zároveň omezuje zbytečné zpřístupňování interních dat.

Vlastní databázové dotazy

Většina WordPress REST endpointů může pracovat prostřednictvím standardních WordPress API.

Pokud je specializovaný přístup k databázi skutečně potřeba, stále používám databázové abstrakce WordPressu a parametrizované dotazy.

Hodnoty z externích požadavků se nesmí nikdy přímo spojovat s raw SQL pomocí konkatenace.

REST vstup je nedůvěryhodný vstup.

JavaScriptové aplikace

WordPress REST API přirozeně spolupracuje s JavaScriptovými aplikacemi.

Frontend může pomocí fetch() nebo jiného HTTP klienta:

• načítat obsah,
• odesílat změny,
• spouštět vlastní akce.

To umožňuje vytvářet výrazně interaktivnější rozhraní WordPressu než tradiční workflow založené na úplném znovunačítání stránky.

Interaktivní rozhraní WordPressu

REST endpointy používám tehdy, když vlastní WordPress rozhraní potřebuje asynchronní funkcionalitu.

Může jít například o:

• filtry,
• vyhledávání,
• dashboardy,
• dynamické seznamy,
• nástroje pro správu obsahu.

Stránka může komunikovat s WordPressem na pozadí a aktualizovat pouze relevantní část stavu rozhraní.

Headless WordPress

REST API může podporovat také headless architektury WordPressu.

V takovém modelu:

WordPress
→ správa obsahu

REST API
→ datové rozhraní

samostatný frontend
→ prezentace

WordPress zůstává redakčním backendem, zatímco uživatelské rozhraní vykresluje jiná aplikace.

Tuto architekturu používám pouze tehdy, pokud projekt ze skutečného oddělení frontendu těží.

Pokud takové oddělení není potřeba, bývá klasické WordPress téma často jednodušší.

Externí aplikace

Protože REST API používá standardní HTTP a JSON, může WordPress komunikovat se softwarem vytvořeným v celé řadě technologií.

Může jít například o:

• Python nástroje,
• Android aplikace,
• desktopový software,
• automatizační služby,
• externí webové aplikace.

Klient nemusí rozumět interní implementaci WordPressu v PHP.

Stačí, když rozumí API kontraktu.

Integrace s Pythonem

Python mohu používat ke komunikaci s WordPressem prostřednictvím REST endpointů například pro:

• automatizaci,
• zpracování obsahu,
• aktualizace metadat,
• synchronizaci,
• extrakci dat.

To je užitečné zejména tehdy, když je určitý úkol jednodušší implementovat mimo samotný WordPress.

WordPress zůstává obsahovým systémem, zatímco Python provádí specializované zpracování.

Integrace s Androidem

Android aplikace může rovněž využívat data z WordPress REST API.

Typická architektura může vypadat takto:

WordPress
↓
REST API
↓
JSON
↓
Kotlin
↓
Android aplikace

To je užitečné v případech, kdy WordPress funguje jako obsahový backend pro mobilní rozhraní.

AI a automatizace

REST API je užitečné také v workflow podporovaných umělou inteligencí.

Například:

obsah WordPressu
↓
REST API
↓
AI zpracování
↓
validace
↓
REST API
↓
aktualizovaná metadata WordPressu

Externí automatizace tak může pracovat s WordPressem bez nutnosti přímého přístupu k databázi.

API funguje jako kontrolovaná integrační hranice.

Webhooky a externí systémy

U integrací s externími systémy mohou REST endpointy tvořit jednu část širší synchronizační architektury.

WordPress může:

• přijímat strukturovaná data,
• zpřístupňovat stav aplikace,
• přijímat výsledky automatizace.

U událostmi řízených workflow lze tento přístup kombinovat s webhookovou komunikací nebo plánovanou synchronizací.

Vlastní aplikace uvnitř WordPressu

REST API není užitečné jen pro zcela externí software.

Může podporovat také pokročilé aplikace vytvořené přímo uvnitř WordPressu.

Vlastní administrační rozhraní může používat REST endpointy pro práci s daty WordPressu a zároveň nabídnout moderní UI založené na JavaScriptu.

Datové operace tak zůstávají oddělené od vykreslování rozhraní.

Zpětná kompatibilita

Jakmile na endpointu závisí jiná aplikace, změna jeho struktury může daného klienta rozbít.

Vlastní REST rozhraní proto považuji za kontrakty.

U vyspělejších integrací preferuji:

• aditivní změny,
• stabilní názvy polí,
• verzované namespace tam, kde jsou nutné nekompatibilní změny.

Interní implementace se tak může vyvíjet bez nutnosti měnit všechny klienty současně.

Dokumentace API

Vlastní API by měla být srozumitelná i bez nutnosti studovat kód, který je vytvořil.

U větších integrací dokumentuji:

• routy,
• metody,
• autentizaci,
• parametry,
• odpovědi,
• chování při chybách.

To snižuje počet budoucích integračních chyb a zjednodušuje údržbu systému.

Bezpečnost

Vývoj vlastních REST endpointů vyžaduje stejný defenzivní přístup jako práce s jakýmkoli jiným veřejným API.

Sleduji zejména:

• autentizaci,
• autorizaci,
• permission callbacky,
• validaci,
• sanitizaci,
• escaping,
• omezení frekvence nebo prostředků tam, kde je to vhodné.

Nikdy nepředpokládám, že endpoint bude volán pouze prostřednictvím rozhraní, které jsem vytvořil.

Pokud je routa dostupná přes HTTP, může se ji jiný klient pokusit zavolat přímo.

WordPress REST API v mém technologickém stacku

WordPress REST API běžně používám společně s technologiemi, jako jsou:

• WordPress,
• PHP,
• Advanced Custom Fields,
• vlastní typy příspěvků,
• vlastní taxonomie,
• JavaScript,
• TypeScript,
• JSON,
• REST API,
• OAuth nebo aplikační autentizace,
• automatizace v Pythonu.

Poskytuje strukturovanou integrační vrstvu mezi WordPressem a systémy mimo jeho běžný proces vykreslování.

Proč používám WordPress REST API

WordPress REST API používám tehdy, když má WordPress fungovat jako něco víc než tradiční serverem vykreslovaný web.

Poskytuje mi standardizovaný způsob, jak zpřístupnit data WordPressu a aplikační funkcionalitu prostřednictvím strukturovaných JSON rozhraní.

Díky tomu lze WordPress propojit s interaktivními webovými aplikacemi, automatizací, mobilním softwarem a externími službami a zároveň jej zachovat jako platformu pro správu obsahu a administraci.

Důležité není pouze zpřístupnit data WordPressu.

Důležité je zpřístupnit správná data prostřednictvím jasného, validovaného API kontraktu s kontrolou oprávnění.

Takto k WordPress REST API přistupuji: jako k mostu mezi WordPressem a zbytkem aplikační architektury.