Az endpointot a saját bővítmény namespace-ében regisztrálja, explicit HTTP-metódusokkal, argumentumokkal, validációval és permission callbackkel. A callback egy különálló alkalmazásszolgáltatást hívjon meg, és stabil sémát vagy strukturált WP_Error-t adjon vissza. Teszteljen anonim és jogosult felhasználóval, határértékes bemenetekkel, lapozással és visszafelé kompatibilitással. A kimenetet explicit resource transformerrel engedélyezze. A belső metamezőket ne adja vissza automatikusan.
Egy egyedi WordPress REST API végpont a webhely egy konkrét funkcióját teszi elérhetővé egy alkalmazás, integráció vagy saját adminisztrációs felület számára. Egy gyors callback, amely visszaadja egy adatbázis-lekérdezés eredményét, működhet az első prototípusban, de stabil szerződés nélkül a kliens nem tudja megkülönböztetni a hibákat, lapozni az adatokat, sem biztonságosan átállni új verzióra. A megvalósítás így a WordPress belső részleteihez kötődő törékeny kapcsolattá válik.
Ez az útmutató egyetlen egyedi endpoint megtervezésére összpontosít a követelménytől a tesztekig. A teljes WordPress REST API réteg általános biztonsága és teljesítménye tágabb téma. Itt a namespace-szel, a route-tal, a bemeneti és kimeneti sémával, a permission callbackkel, a hibamodellel, a szerződés változásaival, valamint az alkalmazáslogika és a transzport szétválasztásával foglalkozunk.
Határozza meg a forrást, a műveletet és a route verzióját
Először írja le az üzleti műveletet és a klienst. A projektlista olvasása, egy kérés létrehozása és az állapot módosítása különböző route-ok, eltérő jogosultságokkal. Az URL nevét az erőforrásból vezesse le, használja a megfelelő HTTP metódust, valamint olyan verziózott namespace-t, amely egy konkrét plugin vagy szervezet tulajdonában van.
A szerződés tartalmazza a paramétereket, típusokat, kötelező jelleget, alapértelmezett értékeket, a kimenetet és a hibákat. Ne tegye közzé a belső táblaneveket vagy a szerializált meta értékeket csak azért, mert könnyen elérhetők. A nyilvános modellnek a tároló módosítása után is stabilnak kell maradnia. A példákat éles tokenek és személyes adatok nélkül dokumentálja.
Regisztrálja az argumentumokat és validálja a jelentésüket
Az argumentum sémája már a callback előtt ellenőrzi a típust, a formátumot, a tartományt és az engedélyezett értékeket. A szanitizálás biztonságos formátumra igazítja az adatot, de nem alakíthat át csendben egy érvénytelen üzleti bemenetet más értékké. Ha az állapot ismeretlen, vagy a dátum az engedélyezett időszakon kívül esik, adjon vissza konkrét kliensoldali hibát stabil kóddal.
A mezők közötti kapcsolatokat is validálja. A záró dátumhoz szükség lehet kezdő dátumra, és a tételnek ahhoz az objektumhoz kell tartoznia, amelyhez kapcsolódik. Íráskor közvetlenül a módosítás előtt töltse be újra az aktuális állapotot, hogy a kliens ne egy régóta érvénytelen feltételezéssel menjen át. A méretkorlát védi a szöveget, a listát és a feltöltést is.
- Típus, tartomány és megengedett értékek
- Jelentésbeli kapcsolatok a paraméterek között
- Kérésméret-korlát
- Stabil hibakód a kliens számára
A permission callbacket kösse az objektumhoz és a művelethez
A hitelesítés csak azt mondja meg, ki indítja a hívást. A permission callback dönti el, hogy végrehajthatja-e az adott műveletet egy konkrét objektumon. A szerepkör nevének ellenőrzése helyett használjon capabilityket és tulajdonjog-ellenőrzést. Listáknál a jogosultsági szűrőt a lekérdezésben alkalmazza, ne csak az összes rekord betöltése és megszámolása után.
A nonce a bejelentkezett WordPress-felületről érkező kérésekhez alkalmas, nem pedig univerzális API-kulcs egy külső szerver számára. A külső hitelesítést a támogatott mechanizmus alapján válassza meg, az átvitelt pedig védje HTTPS-sel. A hibaválasz ne fedje fel, hogy létezik-e egy érzékeny, más tulajdonában lévő objektum, ha a hívónak ehhez nincs jogosultsága.
Válassza szét a controllert, a logikát és a szerializációt
A REST callback beolvassa az ellenőrzött argumentumokat, meghívja az alkalmazásszolgáltatást, és szerializálja az eredményt. Az üzleti logikát ne helyezze közvetlenül a route regisztrációjába, mert akkor sem észszerűen tesztelni, sem CLI-ből vagy sorból használni nem lehet. A szolgáltatás tartományi értékekkel dolgozik, a WordPress transzportobjektumai pedig a peremen maradnak.
A kimenetet egy explicit resource transformer állítja elő, amely csak a meghatározott mezőket engedi át. A dátum, a pénznem és a számok formátuma egységes. A lista felső határral rendelkező limitet, stabil sorrendet és lapozási mechanizmust használ. A költséges származtatott mezőket feltételesen töltse be, vagy gyorsítótárazza pontos érvénytelenítéssel.
Tesztelje a szerződést, és tervezzen kompatibilis változtatásokat
Az automatikus tesztek lefedik a sikeres esetet, a hiányzó paramétert, az érvénytelen típust, a határértéket, a névtelen felhasználót, az elégtelen jogosultságot és az idegen objektumot. Írási műveleteknél tesztelje az ismétlést és az egyidejűséget. Az integrációs teszt a valódi route-ot, a fejléceket, az állapotkódokat és a JSON-t ellenőrzi, nem csupán a belső PHP-metódust.
Egy opcionális mező hozzáadása általában kompatibilis, a jelentés módosítása vagy a mező eltávolítása viszont nem. Nem kompatibilis változtatásnál adjon ki új route-verziót, kövesse nyomon a régi használatát, és biztosítson átmeneti időt az ügyfeleknek. A dokumentáció és a szerződésteszt a kóddal együtt frissül. Az élesítés után a hibákat stabil hibakód alapján monitorozza, ne az érzékeny payloadok tartalma alapján.
Gyakori kérdések
Szüksége van-e minden REST endpointnak permission callbackre?
Igen, a route-nak kifejezetten döntenie kell a hozzáférésről. Egy nyilvános endpoint szándékosan engedélyezheti a névtelen olvasást, de ekkor is meghatározza a hatókört és a limiteket, és nem tehet véletlenül elérhetővé nem nyilvános mezőket.
A nonce hitelesítésre szolgál egy külső alkalmazás számára?
A nonce-t főként bejelentkezett WordPress-munkamenetben használják, és a kérés konkrét kontextusát védi. Egy külső alkalmazásnak megfelelő, támogatott hitelesítési mechanizmusra, biztonságos átvitelre és korlátozott jogosultságokra van szüksége.
Mikor érdemes új verziót létrehozni egy REST route-ból?
Amikor a jelentést, a kötelező mezőket vagy a kimenetet olyan módon változtatja meg, amely a meglévő klienst működésképtelenné teheti. Kompatibilis bővítés hozzáadható az aktuális verzióhoz, ha a szerződés megengedi, és a tesztek ezt igazolják.
Források és további olvasnivaló
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.
