register_rest_route în WordPress

register_rest_route( string $route_namespace, string $route, array $args = array(), bool $override = false ): bool

Ce face register_rest_route

register_rest_route() (din WordPress 4.4.0) adaugă o rută nouă în REST API. Se apelează doar în acțiunea rest_api_init; din 5.1.0 WordPress afișează un avertisment „doing it wrong” dacă o apelezi mai devreme. Namespace-ul are de obicei forma vendor/v1 (de exemplu dex/v1), iar ruta rezultată este https://exemplu.ro/wp-json/dex/v1/....

În $args dai methods (de exemplu WP_REST_Server::READABLE, adică 'GET'), callback (funcția care produce răspunsul) și permission_callback. Din 5.5.0, dacă lipsește permission_callback, apare un avertisment; pentru rute publice folosește '__return_true'. Parametrii din URL se scriu ca expresii regulate cu nume, de exemplu (?P<id>\d+), și se citesc din obiectul WP_REST_Request.

Funcția callback poate întoarce un tablou (transformat în JSON), un WP_REST_Response sau un WP_Error; în datele erorii pui 'status' => 404 ca să alegi codul HTTP. Când permission_callback întoarce false, WordPress răspunde cu eroarea rest_forbidden (401 pentru vizitatori neautentificați, 403 pentru utilizatori fără drept).

Parametri

Parametru	Descriere
$route_namespace	Primul segment după /wp-json/, unic pentru pluginul tău, de exemplu dex/v1.
$route	Ruta de bază, de exemplu /meniu sau /comenzi/(?P<id>\d+).
$args	Opțiunile endpointului: methods, callback, permission_callback, args (definiția parametrilor, cu required, default, validate_callback, sanitize_callback). Poate fi și un tablou de astfel de tablouri, câte unul pe metodă.
$override	true înlocuiește o rută existentă; implicit false (se combină cu ea).

Ce returnează

true la succes, false la eroare.

Exemple

Exemplul 1: Un endpoint public cu meniul cafenelei

Ruta GET /wp-json/dex/v1/meniu, publică prin __return_true. Tabloul întors devine JSON.

<?php
function dex_ruta_meniu() {
    register_rest_route( 'dex/v1', '/meniu', array(
        'methods'             => WP_REST_Server::READABLE,
        'callback'            => 'dex_meniu_cafenea',
        'permission_callback' => '__return_true',
    ) );
}
add_action( 'rest_api_init', 'dex_ruta_meniu' );

function dex_meniu_cafenea() {
    return array(
        array( 'produs' => 'Espresso', 'pret' => 9 ),
        array( 'produs' => 'Cappuccino', 'pret' => 12 ),
    );
}

// În terminal:
// curl https://exemplu.ro/wp-json/dex/v1/meniu

Ieșire în terminal

[{"produs":"Espresso","pret":9},{"produs":"Cappuccino","pret":12}]

Exemplul 2: Rută cu parametru și eroare 404

Parametrul id e validat ca număr, iar când comanda nu există întoarcem WP_Error cu status 404. În JSON, ă apare ca \u0103.

<?php
add_action( 'rest_api_init', function () {
    register_rest_route( 'dex/v1', '/comenzi/(?P<id>\d+)', array(
        'methods'             => 'GET',
        'callback'            => 'dex_comanda',
        'permission_callback' => '__return_true',
        'args'                => array(
            'id' => array(
                'sanitize_callback' => 'absint',
            ),
        ),
    ) );
} );

function dex_comanda( WP_REST_Request $request ) {
    $comanda = get_post( $request['id'] );
    if ( ! $comanda || 'dex_comanda' !== $comanda->post_type ) {
        return new WP_Error( 'dex_nu_exista', 'Comanda nu există.', array( 'status' => 404 ) );
    }
    return array( 'id' => $comanda->ID, 'titlu' => $comanda->post_title );
}

// curl https://exemplu.ro/wp-json/dex/v1/comenzi/999

Ieșire în terminal

{"code":"dex_nu_exista","message":"Comanda nu exist\u0103.","data":{"status":404}}

Exemplul 3: Endpoint doar pentru editori

permission_callback verifică un drept cu current_user_can(). Un vizitator neautentificat primește rest_forbidden cu status 401.

<?php
add_action( 'rest_api_init', function () {
    register_rest_route( 'dex/v1', '/rapoarte', array(
        'methods'             => 'GET',
        'callback'            => 'dex_raport_vanzari',
        'permission_callback' => function () {
            return current_user_can( 'edit_others_posts' );
        },
    ) );
} );

// curl https://exemplu.ro/wp-json/dex/v1/rapoarte

Ieșire în terminal

{"code":"rest_forbidden","message":"Sorry, you are not allowed to do that.","data":{"status":401}}

Greșeli frecvente

• Apelul în afara acțiunii rest_api_init (de exemplu direct în functions.php sau în init): WordPress afișează un avertisment „doing it wrong”.
• Lipsa lui permission_callback: din 5.5 produce un avertisment. Scrie explicit '__return_true' pentru rute publice sau o verificare cu current_user_can().
• Să întorci HTML sau să faci echo în callback: întoarce un tablou, WP_REST_Response sau WP_Error, iar WordPress produce JSON-ul.
• Namespace fără versiune (dex în loc de dex/v1): când schimbi formatul răspunsului nu mai poți păstra varianta veche în paralel.

Comenzi înrudite

• current_user_can: Verifică dacă utilizatorul conectat are un anumit drept (capability), de exemplu manage_options sau edit_post pentru un articol.
• wp_remote_get: Face cereri HTTP din PHP prin HTTP API-ul WordPress și întoarce un tablou cu răspunsul sau un obiect WP_Error.
• sanitize_text_field: Curăță textul de pe o singură linie primit de la utilizator: elimină HTML-ul, rândurile noi, tab-urile și spațiile în plus.