REST API vagy admin-ajax.php? Így dönts WordPressben

Ha WordPressben interaktív UI-t építesz (szűrők, kereső autocomplete, „Load more”, beállítások mentése JS-ből), előbb-utóbb előkerül a kérdés: admin-ajax.php vagy REST API? Sok kódbázisban még mindig reflexből az admin-ajax.php jön, pedig a WordPress REST API évek óta core funkció, és ma már ez a normális út.

Na, nézzük meg fejlesztői szemmel: miért problémás az admin-ajax.php, mit ad ehhez képest a REST API, és hogyan néz ki egy vállalható, modern endpoint + fetch() kliensoldalon.

Mi a gond az admin-ajax.php-val?

Az admin-ajax.php egy régi mechanizmus, ami még a REST API előtti időkből maradt velünk. Működik, persze. A baj az, hogy olyan árat fizetsz érte, amit sokszor észre sem veszel, amíg nem lesz belőle lassulás, „minden POST”, meg nehezen karbantartható action-spagetti.

• Teljesítmény: egy admin-ajax.php hívásnál a WordPress admin környezetből is sok minden betöltődik, akkor is, ha neked csak egy JSON választ kellene visszaadni.
• Nincs értelmes HTTP metódus kezelés: jellemzően minden POST, ami API-tervezésben elég rossz jel. Nem lesz szemantikus, nem lesz „önmagát dokumentáló”.
• Korlátozott struktúra: az egész egy action string köré épül. Nincs natív routing élmény, nincs olyan kényelmes paraméterkezelés/validációs keret, mint REST route-oknál.

Mit kapsz a WordPress REST API-tól?

A REST API a WordPressben a /wp-json/ alá szervezett, verziózható endpoint rendszer. A lényeg az, hogy normális route-okat kapsz, HTTP metódusokkal, és egy olyan struktúrát, amihez a modern frontend (React/Vue/Svelte, vagy sima vanilla JS) természetesen tud kapcsolódni.

• Biztonság beépítve: a permission_callback miatt muszáj végiggondolnod, ki férhet hozzá az endpointodhoz. Ez jó kényszer.
• REST-es működés: GET, POST, PUT/PATCH, DELETE – azt használod, amit a művelet jelentése indokol.
• Jobb teljesítmény: tipikusan kisebb overhead, gyorsabb válaszidő, kevesebb szerverterhelés.
• Ipari standard: REST-et mindenki ismeri, könnyebb integrálni külső toolokkal, és új fejlesztőnek sem „WordPress-mágia” az egész.
• Automatikus felfedezhetőség: a WP listázza az endpointjaidat a REST indexben, így teszteléshez és integrációhoz is kényelmesebb.

Egy tiszta REST endpoint példa (PHP)

A következő példa egy minimál, de vállalható REST route. A namespace itt app/v1 (a verziózás miatt jó szokás), és egy GET végpontot adunk vissza. A trükk a permission_callback: itt döntöd el, hogy ki hívhatja.

<?php

add_action('rest_api_init', function () {
    register_rest_route('app/v1', '/endpoint', [
        'methods'  => 'GET',
        'callback' => 'app_v1_endpoint_callback',

        // Itt dől el a hozzáférés. Példa: csak admin jogosultsággal.
        'permission_callback' => fn () => current_user_can('manage_options'),
    ]);
});

function app_v1_endpoint_callback(WP_REST_Request $request) {
    return [
        'status'  => 'ok',
        'message' => 'It works!',
    ];
}

Kliensoldali hívás fetch()-sel (JavaScript)

A REST endpoint hívása frontendről teljesen standard: fetch(), metódus, JSON parse, kész. A URL a WP-ben a /wp-json/ prefixszel áll össze.

fetch('/wp-json/app/v1/endpoint', {
  method: 'GET',
})
  .then((response) => response.json())
  .then((data) => {
    console.log('Success:', data);
  })
  .catch((error) => {
    console.error('Error:', error);
  });

Mikor melyiket használd?

Itt érdemes pragmatikusan gondolkodni. Nem az a cél, hogy mindent holnap átírj, hanem hogy új kód ne a régi mintákat erősítse.

1. REST API: új feature, új projekt, bármilyen AJAX jellegű interakció, ami JSON-t ad/kap, és fontos a karbantarthatóság.
2. admin-ajax.php: akkor, ha legacy kódot tartasz életben, és az átírás költsége nem hoz arányos nyereséget (idő, kockázat, regresszió).

Átállás fejben: admin-ajax.php mint „legacy réteg”

A WordPress REST API a core része (évek óta), és a modern WordPress fejlesztés természetes alapja. Ha ma új endpointot írsz, és reflexből az admin-ajax.php-hoz nyúlsz, az kb. olyan, mintha új projektben jQuery-re építenéd az interakciókat: működik, csak közben magadra húzol egy csomó régi kompromisszumot.

A lényeg: REST route-okkal tisztább lesz a kódod, jobban skálázódik a rendszer, és a biztonságot sem utólag kell „rákötözni”.

Összefoglaló

• Az admin-ajax.php legacy megoldás: admin környezet overhead, kevésbé szemantikus API, nehezebb struktúra.
• A REST API route-okat, HTTP metódusokat, jobb integrálhatóságot és kényelmesebb tesztelhetőséget ad.
• A permission_callback jó értelemben kényszerít rá, hogy jogosultságot tervezz, ne utólag foltozz.
• Új fejlesztéshez REST API, admin-ajax.php inkább csak karbantartandó örökséghez.