WP REST API for headless og tilpassede endepunkter: Utviklerguiden

#Hvorfor de innebygde /wp/v2/-endepunktene ikke alltid er nok

Det innebygde offentlige API-et under navnerommet /wp-json/wp/v2/ dekker innlegg, sider, kategorier, stikkord og metadata. For enkle lesescenarier fungerer det rett ut av boksen. Når applikasjonen blir mer kompleks, dukker det likevel opp tre begrensninger:

1. For mye data overføres (over-fetching): en forespørsel til /wp/v2/posts returnerer en rekke hjelpefelter, HAL-lenker, forfatterobjekter og kommentardata som en lett frontend-komponent ofte ikke trenger.
2. Kjedede forespørsler (under-fetching / N+1): trenger du et innlegg, det tilknyttede WooCommerce-produktet og brukervurderingene, tvinger standard-API-et frontenden til å sende flere forespørsler etter hverandre, og nettverksforsinkelsen multipliseres.
3. Eksponert domenelogikk: komplekse forretningsregler, som tilbudsberegning i sanntid, lagersjekk mot et eksternt lager eller validering av skjemaer i flere trinn, hører ikke hjemme i frontend-klienten. De bør pakkes inn i et dedikert endepunkt på serveren.

Det riktige arkitektoniske svaret er å registrere egne ruter med funksjonen register_rest_route().

#Slik lager du et eget REST API-endepunkt i WordPress

Når du skal opprette en ny API-rute, må du aldri injisere rå header()-kall eller avbryte vanlige sidemaler. WordPress tilbyr en formell livssykluskrok kalt rest_api_init.

Inne i denne kroken brukes funksjonen register_rest_route(). Den krever tre hovedelementer:

1. Navnerom (Namespace): En unik streng med versjonsnummer, for eksempel wppoland/v1. Dette forhindrer kollisjoner med kjernen eller utvidelser fra tredjeparter.
2. Rute (Route): Den relative URL-stien, som kan inneholde regulære uttrykk for parametere (f.eks. /produkter/(?P<id>\d+)).
3. Alternativer (Options array): Definerer HTTP-metoder, tilgangskontroll, valideringsskjema og selve kjørefunksjonen.

#Eksempel på register_rest_route() for produktdata

Tenk deg et scenario der en ekstern frontend-applikasjon kun trenger tittel, pris og lagerstatus for utvalgte produkter, uten å måtte laste hundrevis av linjer med unødvendig Gutenberg-blokkdata:

/**
 * Registrerer tilpassede REST API-ruter for prosjektet.
 */
function wppoland_registrer_rest_ruter(): void {
    register_rest_route(
        'wppoland/v1',
        '/utvalgte-produkter',
        array(
            'methods'             => \WP_REST_Server::READABLE, // Equivalent to GET
            'callback'            => 'wppoland_hent_utvalgte_produkter_respons',
            'permission_callback' => '__return_true', // Public route
            'args'                => array(
                'antall' => array(
                    'default'           => 5,
                    'sanitize_callback' => 'absint',
                    'validate_callback' => function( $param ) {
                        return filter_var($param, FILTER_VALIDATE_INT) !== false && $param > 0 && $param <= 50;
                    },
                ),
            ),
        )
    );
}
add_action( 'rest_api_init', 'wppoland_registrer_rest_ruter' );

Legg merke til bruken av konstanten \WP_REST_Server::READABLE i stedet for den hardkodede strengen 'GET'. Dette sikrer samsvar med interne filtre i WordPress.

#Validere og vaske parametere i WordPress REST API

En av de vanligste feilene i WordPress-endepunkter er å behandle parametere direkte i tilbakeringingsfunksjonen uten å validere dem først. REST API-arkitekturen har en egen mekanisme for dette i args-matrisen:

1. validate_callback: kontrollerer om innkommende data oppfyller den forventede kontrakten før hovedlogikken kjøres. Returnerer den false eller et WP_Error-objekt, stopper WordPress behandlingen og svarer automatisk med 400 Bad Request.
2. sanitize_callback: transformerer og renser inndataverdien (for eksempel med sanitize_text_field, absint eller esc_url_raw) før den sendes videre til tilbakeringingsfunksjonen.

Argumentvalidering håndhever inndatakontrakten. SQL-spørringer trenger fortsatt forberedte spørringer (prepared statements), og HTML-utdata trenger escaping tilpasset konteksten. Håndboken for egne endepunkter anbefaler i tillegg et unikt navnerom etter mønsteret vendor/v1, der vendor normalt er slugen til utvidelsen eller temaet.

#Sikre WordPress REST API-endepunkter med permission_callback

Et av de største sikkerhetshullene i eldre WordPress-kodebaser har vært mangelfull tilgangskontroll på egendefinerte endepunkter.

Tidligere var permission_callback valgfri, noe som førte til at mange utviklere glemte å sikre ruter som utførte sensitive handlinger som å oppdatere brukerprofiler eller slette innlegg. I moderne WordPress utløser fravær av denne tilbakeringen en feilmelding i feilsøkingsmodus.

#Hvordan beskytte administrative endepunkter med current_user_can()

Dersom endepunktet skal oppdatere data eller lese intern forretningsstatistikk, må du verifisere brukerens rettigheter via current_user_can():

register_rest_route(
    'wppoland/v1',
    '/oppdater-status/(?P<id>\d+)',
    array(
        'methods'             => \WP_REST_Server::EDITABLE, // POST, PUT, PATCH
        'callback'            => 'wppoland_oppdater_ordre_status',
        'permission_callback' => function( \WP_REST_Request $request ) {
            // Verify permissions for the requested resource.
            return current_user_can( 'edit_posts' );
        },
    )
);

#Offentlige REST-ruter og CSRF-beskyttelse med nonce

Hvis ruten skal være åpen for uautentiserte besøkende (for eksempel et offentlig nyhetsvarsel eller et kontaktskjema), skal du eksplisitt oppgi 'permission_callback' => '__return_true'.

For operasjoner som mottar data fra innloggede brukere i en nettleser (samme domene), krever WordPress en gyldig nonce-kode i HTTP-forespørselshodet: X-WP-Nonce: [generert nonce] Uten dette vil WordPress avvise forespørselen med HTTP-kode 403 for å forhindre Cross-Site Request Forgery (CSRF).

#Autentisering mot WordPress REST API i headless-oppsett

Når WordPress snakker med eksterne servere, mobilapper eller byggeskripter, kan du ikke stole på standard nettleserkapsler. Følgende tre metoder er industristandard i 2026:

1. Application Passwords (Innebygd)
   ├── Bruk: Server-til-server, cron-jobber, migreringsskripter
   └── Protokoll: HTTP Basic Auth med unike, tilbakekallbare nøkler

2. JWT (JSON Web Tokens)
   ├── Bruk: Mobilapper, Single Page Applications med brukerinnlogging
   └── Protokoll: Bearer-token i Authorization-header etter passordbekreftelse

3. OAuth 2.0
   ├── Bruk: Tredjeparts økosystemer og bedriftsintegrasjoner
   └── Protokoll: Tidsbegrensede tokens med definerte tilgangsnivåer (scopes)

Application Passwords er integrert direkte i WordPress-kjernen. Hver bruker kan generere et unikt passord under sin profil som kun har tilgang til REST API, og som umiddelbart kan slettes dersom en nøkkel kommer på avveie, uten at hovedpassordet må endres.

#Caching av WordPress REST API-responser

Hvert eneste kall til /wp-json/ laster inn hele WordPress-arkitekturen: wp-config.php, aktive utvidelser, temaets functions.php og databasekoblingen. Hvis en frontend-applikasjon henter hundre API-kall per minutt, vil serverens PHP-arbeidere raskt bli overbelastet.

#Caching med Transients API

For komplekse beregninger eller tunge SQL-spørringer som sjelden endrer seg, bør resultatet lagres i minnet:

/**
 * Tilbakeringingsfunksjon med integrert transient-caching.
 */
function wppoland_hent_utvalgte_produkter_respons( \WP_REST_Request $request ): \WP_REST_Response {
    $antall     = (int) $request->get_param( 'antall' );
    $cache_nokkel = 'wppoland_rest_produkter_' . $antall;

    $data = get_transient( $cache_nokkel );

    if ( false === $data ) {
        $query = new \WP_Query( array(
            'post_type'      => 'product',
            'post_status'    => 'publish',
            'posts_per_page' => $antall,
            'no_found_rows'  => true,
            'fields'         => 'ids',
        ) );

        $data = array();
        foreach ( $query->posts as $post_id ) {
            $data[] = array(
                'id'          => $post_id,
                'tittel'      => get_the_title( $post_id ),
                'nettadresse' => get_permalink( $post_id ),
                'pris'        => get_post_meta( $post_id, '_price', true ),
            );
        }

        // Cache for four hours.
        set_transient( $cache_nokkel, $data, 4 * HOUR_IN_SECONDS );
    }

    $respons = new \WP_REST_Response( $data, 200 );
    
    // Public cache policy; configure the proxy separately.
    $respons->header( 'Cache-Control', 'public, max-age=3600, s-maxage=7200' );

    return $respons;
}

#Hvordan redusere JSON-svar med _fields-parameteren

Dersom du bruker standardendepunktene til WordPress (f.eks. /wp/v2/posts), inneholder hvert objekt hundrevis av felter som forfatterkoblinger, formater, ping-status og GUID-er.

I klientskriptet bør du alltid legge til parameteren _fields: https://eksempel.no/wp-json/wp/v2/posts?per_page=10&_fields=id,title,slug,date Dette begrenser feltene i svaret. Mål overføring, parsingtid og feltforberedelse med egne data for å fastslå virkningen.

#WordPress REST API med Astro og Next.js

I en moderne frakoblet arkitektur fungerer WordPress utelukkende som et administrasjonsgrensesnitt for redaktørene, mens frontenden kompileres til statisk HTML via rammeverk som Astro.

Når en redaktør klikker “Publiser” i WordPress, sendes en webhook til byggesystemet (f.eks. Cloudflare Pages eller GitHub Actions), som kaller de nødvendige REST-endepunktene. Byggetiden avhenger av innholdsmengde og pipeline.

Dette gir overlegen sikkerhet:

• Den offentlige nettsiden har ingen tilkobling til MySQL under kjøring.
• WordPress-opprinnelsen må fortsatt beskytte innlogging, database og API selv om den offentlige frontenden er statisk.
• Frontenden må fortsatt måles og optimaliseres for Google Core Web Vitals.

#En svarkontrakt som tåler flere klienter

Start med dataene mottakeren trenger. En liste over redaksjonelle anbefalinger kan returnere publiserte innlegg, mens en ERP-integrasjon også trenger stabile identifikatorer, endringstidspunkt og en dokumentert måte å fortsette en avbrutt import på. En tom samling, en manglende ressurs og en midlertidig databasefeil krever forskjellig oppførsel i klienten. Tomme søkeresultater kan være et vellykket svar. En databasefeil skal ikke bli en tom liste som får mottakeren til å slette lokale produkter.

Beskriv om et felt kan være null, mangle helt eller inneholde tom tekst. Et produkt uten bilde er ikke det samme som et produkt som ikke er publisert. Identifikatoren må bestå når redaktøren endrer slug. Feilkoder bør være uavhengige av oversatt meldingstekst, slik at en norsk butikk og et engelsk administrasjonspanel håndterer samme problem. Avtal tidssone og om beløp inkluderer merverdiavgift. REST fastsetter ikke disse forretningsreglene. En mottaker som tolker bruttopris som nettopris, får feil selv om JSON-formatet er gyldig.

WordPress-dokumentasjonen for egne endepunkter beskriver registrering, argumenter og svarobjekter. Eksemplene er et utgangspunkt. En prosjektrute trenger fortsatt et svarskjema og en integrasjonstest som kontrollerer kontrakten. Et nytt valgfritt felt er normalt forenlig med eksisterende klienter. Endring av navn eller datatype trenger en migreringsplan. Behold det gamle navnerommet mens publiserte mobilapper og partnerintegrasjoner bruker det. Registrer hvilke klientversjoner som fortsatt kaller den gamle ruten før den fjernes.

#Parametergrenser og tilgang til det konkrete objektet

Valider den opprinnelige verdien før sanitering endrer den. absint kan gjøre en negativ verdi om til et tilsynelatende gyldig positivt tall. En egen validate_callback med bare is_numeric godtar også desimaltall og verdier over grensen. Bruk registrert integer-skjema med minimum og maximum, eller pakk inn rest_validate_request_arg når du trenger flere regler. Test null, negative tall, desimaler, eksponentnotasjon, arrays og verdier over grensen. Et begrenset felt i nettleseren stopper ikke en direkte HTTP-forespørsel med en svært stor sidestørrelse.

En autentisert bruker har ikke automatisk tilgang til alle objekter. Ved oppdatering av innlegg kan du kontrollere current_user_can('edit_post', $id). For WooCommerce-bestillinger gjelder rettighetene og eierskapet til den aktuelle ressursen. En generell edit_posts-kontroll er ikke riktig adgangskontroll for kundebestillinger. Kunden må ikke få lese en annen kundes ordre ved å sende dens identifikator. Hent kundeidentiteten fra den autentiserte konteksten, ikke fra en bruker-ID i request-body. Test også direkte tilgang til et skjult produkt, ikke bare om produktet mangler i listevisningen.

Cookie-autentisering trenger både WordPress-sesjonen og REST-nonce. Uten nonce behandler WordPress forespørselen som anonym. Et ugyldig nonce følger en annen feilbane. Nonce erstatter ikke capability-kontroll. Application Passwords bruker rettighetene til den tilknyttede WordPress-brukeren og oppretter ikke automatisk smale forretningsscopes. Lag en egen integrasjonskonto med nødvendige rettigheter, oppbevar passordet serverseitig og tilbakekall den bestemte nøkkelen når integrasjonen avsluttes. JWT-utstedelse er ikke innebygd i WordPress core og krever en separat vurdert implementering. Se dokumentasjonen om autentisering.

#Paginering og grenser for cache

Begrens samlingsstørrelsen og bruk en deterministisk sortering. Når flere poster deler samme endringstidspunkt, bruk en stabil identifikator som ekstra sorteringskriterium. Ellers kan en import som fortsetter mellom sider hoppe over eller gjenta poster. Offset fungerer for en liten redaksjonell liste. En katalog som endres ofte kan trenge en applikasjonsdefinert cursor. Beskriv hva som skjer hvis et produkt slettes, hvordan cursoren utløper og hvordan klienten kjenner igjen siste side. Ikke oppgi et totalantall som er beregnet fra gjeldende side når no_found_rows har deaktivert tellingen.

Cache-nøkkelen må inneholde alt som påvirker resultatet: normaliserte filtre, språk, side eller cursor, feltutvalg og relevant kundegruppe. En offentlig katalogcache må utelukke utkast, private metadata og kundespesifikke priser. Begynn med Cache-Control: private, no-store for konto- og ordresvar, og konfigurer edge-laget til å hoppe over caching av disse rutene. Test gjennom den virkelige proxyen med to brukere. En korrekt PHP-header retter ikke en CDN-regel som deler et privat svar mellom kontoer. Kontroller også at en anonym forespørsel etter en autentisert forespørsel ikke får gjenbrukt samme svar.

Transients kan lagres i databasen eller en ekstern objektcache. De kan forsvinne før utløpstiden, så applikasjonen trenger en trygg vei ved cache-miss. Invalidering må dekke sletting, statusendringer og oppdateringer av tilknyttede taksonomier. Lagerendringer kan skje utenfor save_post; bruk hendelsene fra den faktiske handelsintegrasjonen. HTTP-headere alene garanterer ikke at Cloudflare cacher JSON. Sjekk regelen, nøkkelen og observerte cache-statuser i produksjonsmiljøet. Avtal hvor gammel lagerinformasjon klienten kan vise, og bruk et ferskt oppslag før en operasjon som krever gjeldende beholdning.

#Tester som dekker avslag og feil

Bruk WP_REST_Request og rest_do_request i et WordPress-testmiljø. Test offentlig lesing, feil argumenter, manglende autentisering, en gyldig konto uten nødvendige rettigheter og en konto som har tilgang til det konkrete objektet. Kontroller HTTP-status, svarstruktur og cache-headere. Legg inn en upublisert post i testdataene og bekreft at anonyme lister utelater den. For skriveruter må du også bekrefte at en avvist forespørsel ikke endrer databasen. En test som bare kontrollerer feilmeldingen oppdager ikke en endring som allerede skjedde før avslaget.

Mål kalde og varme forespørsler separat. Registrer databasetid, antall spørringer, svarstørrelse og ventetid mot eksterne lagertjenester. _fields kan redusere overføring og forberedelse av støttede felt, men gevinsten avhenger av ruten. Det erstatter ikke selektive databasespørringer. Dokumentasjonen om globale parametre forklarer mekanismen. Vis egne måleresultater med beskrivelse av testdata og miljø fremfor en universell prosentvis forbedring.

Eksterne oppslag trenger timeout og et definert feilsvar. Gjenta lesing med et begrenset antall forsøk og en pause mellom forsøkene. Gjenta skriving bare når mottakeren tilbyr idempotens eller en tilsvarende kontrakt for å oppdage duplikater. Logg korrelasjons-ID, rute, status og varighet. Passord, bearer-tokens, kundeadresser og komplette request-bodies skal ikke være vanlige loggdata. Test produksjonens vertsnavn etter utrulling, inkludert reverse proxy og autentiseringsheadere. Et PHP-testmiljø dekker ikke hele leveringskjeden.

#Sjekkliste for egne REST API-endepunkter

Når du designer egendefinerte REST API-endepunkter i WordPress:

1. Bruk alltid navnerom med versjonering (leverandor/v1).
2. Knytt alltid en streng permission_callback til hver eneste rute.
3. Valider og vask inndata i args-definisjonen før data når tilbakeringingsfunksjonen.
4. Returner strukturerte WP_Error-objekter med nøyaktige HTTP-statuskoder ved feil.
5. Skjerm MySQL-databasen med Transients API eller en Redis-objektcache.

Dersom du planlegger å modernisere din eksisterende infrastruktur eller migrere fra en treg monolit til en moderne frakoblet arkitektur, kan du lese mer om hvordan vi utfører WordPress-migreringer til Astro og Next.js.