Endpoint registrujte v namespace vlastního pluginu s explicitními HTTP metodami, argumenty, validací a permission callbackem. Callback ať volá samostatnou aplikační službu a vrací stabilní schéma nebo strukturovaný WP_Error. Testujte anonymního i oprávněného uživatele, hraniční vstupy, stránkování a zpětnou kompatibilitu. Výstup povolujte explicitním resource transformerem. Interní meta pole automaticky nevracejte.
Vlastní WordPress REST API endpoint zpřístupňuje konkrétní funkci webu aplikaci, integraci nebo vlastnímu administračnímu rozhraní. Rychlý callback, který vrátí výsledek databázového dotazu, může fungovat v prvním prototypu, ale bez stabilního kontraktu klient nedokáže rozlišit chybu, stránkovat data ani bezpečně přejít na novou verzi. Implementace se pak stává křehkou vazbou na interní detaily WordPressu.
Tento návod se zaměřuje na návrh jednoho vlastního endpointu od požadavku po testy. Obecná bezpečnost a výkon celé vrstvy WordPress REST API jsou širší téma. Zde řešíme namespace, route, schéma vstupu a výstupu, permission callback, chybový model, změny kontraktu a oddělení aplikační logiky od transportu.
Definujte zdroj, operaci a verzi route
Nejprve popište obchodní operaci a klienta. Čtení seznamu projektů, vytvoření požadavku a změna stavu jsou odlišné route s jinými oprávněními. Název URL odvoďte od zdroje, používejte správnou HTTP metodu a namespace s verzí, který vlastní konkrétní plugin nebo organizace.
Kontrakt zahrnuje parametry, typy, povinnost, výchozí hodnoty, výstup a chyby. Neodhalujte interní názvy tabulek ani serializované meta hodnoty jen proto, že jsou snadno dostupné. Veřejný model má zůstat stabilní i po změně úložiště. Příklady dokumentujte bez produkčních tokenů a osobních údajů.
Registrujte argumenty a validujte význam
Schema argumentu kontroluje typ, formát, rozsah a povolené hodnoty ještě před callbackem. Sanitizace upraví bezpečný formát, ale nemá potichu změnit neplatný obchodní vstup na jinou hodnotu. Pokud je stav neznámý nebo datum mimo povolené období, vraťte konkrétní klientskou chybu se stabilním kódem.
Validujte i vztahy mezi poli. Datum konce může vyžadovat datum začátku a položka musí patřit k objektu, ke kterému se připojuje. Při zápisu znovu načtěte aktuální stav těsně před změnou, aby klient neprošel s dávno neplatným předpokladem. Limit velikosti chrání text, seznam i nahrávané soubory.
- Typ, rozsah a povolené hodnoty
- Významové vztahy mezi parametry
- Limit velikosti požadavku
- Stabilní chybový kód pro klienta
Permission callback važte na objekt a akci
Autentizace pouze říká, kdo volá. Permission callback rozhodne, zda smí provést danou akci nad konkrétním objektem. Používejte capabilities a ověření vlastnictví místo kontroly názvu role. U seznamu aplikujte filtr oprávnění v dotazu, nikoli až po načtení a spočítání všech záznamů.
Nonce je vhodný pro požadavky z přihlášeného rozhraní WordPressu, nikoli jako univerzální API klíč pro externí server. Externí autentizaci zvolte podle podporovaného mechanismu a přenos chraňte pomocí HTTPS. Chybová odpověď nemá prozradit, zda citlivý cizí objekt existuje, pokud k tomu volající nemá oprávnění.
Oddělte controller, logiku a serializaci
REST callback přečte ověřené argumenty, zavolá aplikační službu a serializuje výsledek. Obchodní logiku nevkládejte přímo do registrace route; pak ji nelze rozumně testovat ani použít z CLI nebo fronty. Služba pracuje s doménovými hodnotami a transportní objekty WordPressu zůstávají na okraji.
Výstup tvoří explicitní resource transformer, který povoluje pouze určená pole. Datum, měna a čísla mají konzistentní formát. Seznam používá limit s horní hranicí, stabilní pořadí a stránkovací mechanismus. Náročná odvozená pole načítejte podmíněně nebo je cachujte s přesnou invalidací.
Testujte kontrakt a plánujte kompatibilní změny
Automatické testy pokryjí úspěch, chybějící parametr, neplatný typ, hraniční hodnotu, anonymního uživatele, nedostatečné oprávnění a cizí objekt. U zápisu testujte opakování a souběh. Integrační test ověří skutečnou route, hlavičky, stavové kódy a JSON, nikoli pouze vnitřní PHP metodu.
Přidání volitelného pole bývá kompatibilní, změna významu nebo odstranění nikoli. Při nekompatibilní změně vydejte novou verzi route, sledujte používání staré a klientům umožněte přechod. Dokumentace a test kontraktu se aktualizují spolu s kódem. Po nasazení monitorujte chyby podle stabilního kódu, nikoli obsah citlivých payloadů.
Časté dotazy
Potřebuje každý REST endpoint permission callback?
Ano, route má o přístupu explicitně rozhodnout. Veřejný endpoint může záměrně povolit anonymní čtení, ale stále definuje rozsah a limity a nesmí náhodně zpřístupnit neveřejná pole.
Je nonce autentizace pro externí aplikaci?
Nonce se používá především u přihlášené WordPress relace a chrání konkrétní kontext požadavku. Externí aplikace potřebuje vhodný podporovaný autentizační mechanismus, bezpečný přenos a omezená oprávnění.
Kdy vytvořit novou verzi REST route?
Když měníte význam, povinná pole nebo výstup způsobem, který může rozbít existujícího klienta. Kompatibilní rozšíření lze přidat do aktuální verze, pokud to kontrakt povoluje a testy to potvrdí.
Zdroje a další čtení
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
