Endpoint registrujte v namespac-e vlastného pluginu s explicitnými HTTP metódami, argumentmi, validáciou a permission callbackom. Callback nech volá samostatnú aplikačnú službu a vracia stabilnú schému alebo štruktúrovanú WP_Error. Testujte anonymného aj oprávneného používateľa, hraničné vstupy, stránkovanie a spätnú kompatibilitu. Výstup povoľujte explicitným resource transformerom. Interné meta polia nevracajte automaticky.
Vlastný WordPress REST API endpoint sprístupňuje konkrétnu funkciu webu aplikácii, integrácii alebo vlastnému administračnému rozhraniu. Rýchly callback, ktorý vráti výsledok databázového dotazu, môže fungovať v prvom prototype, no bez stabilného kontraktu nevie klient rozlíšiť chybu, stránkovať dáta ani bezpečne prejsť na novú verziu. Implementácia sa potom stáva krehkou väzbou na interné detaily WordPressu.
Tento návod sa sústreďuje na návrh jedného vlastného endpointu od požiadavky po testy. Všeobecná bezpečnosť a výkon celej WordPress REST API vrstvy sú širšia téma. Tu riešime namespace, route, schému vstupu a výstupu, permission callback, chybový model, zmeny kontraktu a oddelenie aplikačnej logiky od transportu.
Definujte zdroj, operáciu a verziu route
Najprv popíšte obchodnú operáciu a klienta. Čítanie zoznamu projektov, vytvorenie požiadavky a zmena stavu sú odlišné route s inými oprávneniami. Názov URL odvoďte od zdroja, používajte správnu HTTP metódu a namespace s verziou, ktorú vlastní konkrétny plugin alebo organizácia.
Kontrakt zahŕňa parametre, typy, povinnosť, predvolené hodnoty, výstup a chyby. Neodhaľujte interné názvy tabuliek či serializované meta hodnoty iba preto, že sú ľahko dostupné. Verejný model má byť stabilný aj po zmene úložiska. Príklady dokumentujte bez produkčných tokenov a osobných údajov.
Registrujte argumenty a validujte význam
Schema argumentu kontroluje typ, formát, rozsah a povolené hodnoty ešte pred callbackom. Sanitizácia upraví bezpečný formát, ale nemá potichu premeniť neplatný obchodný vstup na inú hodnotu. Ak je stav neznámy alebo dátum mimo povoleného obdobia, vráťte konkrétnu klientsku chybu so stabilným kódom.
Validujte aj vzťahy medzi poľami. Dátum konca môže vyžadovať začiatok a položka musí patriť objektu, ku ktorému sa pripája. Pri zápise znovu načítajte aktuálny stav tesne pred zmenou, aby klient neprešiel s dávno neplatným predpokladom. Limit veľkosti chráni text, zoznam aj upload.
- Typ, rozsah a povolené hodnoty
- Významové vzťahy medzi parametrami
- Limit veľkosti požiadavky
- Stabilný chybový kód pre klienta
Permission callback viažte na objekt a akciu
Autentifikácia iba hovorí, kto volá. Permission callback rozhodne, či smie vykonať danú akciu nad konkrétnym objektom. Používajte capabilities a overenie vlastníctva namiesto kontroly názvu roly. Pri zozname filter oprávnenia aplikujte v dotaze, nie až po načítaní a spočítaní všetkých záznamov.
Nonce je vhodný pre požiadavky z prihláseného WordPress rozhrania, nie univerzálny API kľúč pre externý server. Externú autentifikáciu vyberte podľa podporovaného mechanizmu a transport chráňte HTTPS. Chybová odpoveď nemá odhaliť, či citlivý cudzí objekt existuje, keď na to volajúci nemá právo.
Oddeľte controller, logiku a serializáciu
REST callback prečíta overené argumenty, zavolá aplikačnú službu a serializuje výsledok. Obchodnú logiku nevkladajte priamo do registrácie route; potom ju nemožno rozumne testovať ani použiť z CLI alebo fronty. Služba pracuje s doménovými hodnotami a transportné objekty WordPressu zostávajú na okraji.
Výstup tvorí explicitný resource transformer, ktorý povoľuje iba určené polia. Dátum, menu a čísla majú konzistentný formát. Zoznam používa limit s hornou hranicou, stabilné poradie a stránkovací mechanizmus. Nákladné odvodené polia načítavajte podmienene alebo cacheujte s presnou invalidáciou.
Testujte kontrakt a plánujte kompatibilné zmeny
Automatické testy pokryjú úspech, chýbajúci parameter, neplatný typ, hraničnú hodnotu, anonymného používateľa, nedostatočné oprávnenie a cudzí objekt. Pri zápise testujte opakovanie a súbeh. Integračný test overí skutočnú route, hlavičky, stavové kódy a JSON, nie iba vnútornú PHP metódu.
Pridanie voliteľného poľa býva kompatibilné, zmena významu alebo odstránenie nie. Pri nekompatibilnej zmene vydajte novú verziu route, sledujte používanie starej a klientom dajte prechod. Dokumentácia a test kontraktu sa aktualizujú spolu s kódom. Po nasadení monitorujte chyby podľa stabilného kódu, nie obsah citlivých payloadov.
Časté otázky
Potrebuje každý REST endpoint permission callback?
Áno, route má explicitne rozhodnúť o prístupe. Verejný endpoint môže zámerne povoliť anonymné čítanie, ale stále definuje rozsah, limity a nesmie náhodne sprístupniť neverejné polia.
Je nonce autentifikácia pre externú aplikáciu?
Nonce sa používa najmä pri prihlásenej WordPress relácii a chráni konkrétny kontext požiadavky. Externá aplikácia potrebuje vhodný podporovaný autentifikačný mechanizmus, bezpečný transport a obmedzené oprávnenia.
Kedy vytvoriť novú verziu REST route?
Keď meníte význam, povinné polia alebo výstup spôsobom, ktorý môže rozbiť existujúceho klienta. Kompatibilné rozšírenie možno pridať do aktuálnej verzie, ak ho kontrakt povoľuje a testy to potvrdia.
Zdroje a ďalšie čítanie
Web developer zo Spišskej Novej Vsi. Venuje sa WordPressu, WooCommerce, vlastným pluginom, API integráciám, webovým aplikáciám a praktickým AI automatizáciám.
