Sådan integrerer du API’er på din hjemmeside

Hvad et API er, kort fortalt

Et API er et sæt adresser, et andet system stiller til rådighed, og regler for, hvad du kan sende og få tilbage. Din side sender en request til fx /orders med en nøgle, der viser, hvem den er, og får et svar tilbage, som regel i JSON. Mange web-API’er er bygget som REST, men GraphQL, gRPC og webhooks er også udbredte. Forskellene gennemgår vi i guiden om REST, GraphQL og gRPC. For resten af denne guide er det nok at vide, at hvert kald går over nettet, tager tid og kan fejle.

Tre måder at integrere på

Start med at se, om der findes et vedligeholdt plugin fra den ene af de to leverandører. Det løser mange standardopgaver. En integrationsplatform er god til at prøve et flow af eller til ting, der sker nogle gange om dagen. Egen kode giver mening, når reglerne er dine egne, eller når mængden gør de andre løsninger dyre eller langsomme.

Det skal du beslutte først

Mange integrationer går galt, fordi ingen har besluttet, hvilket system der har ret. Hvis både webshoppen og lagersystemet kan ændre en vare, hvilket af dem vinder så? Bestem for hver type data, hvor den ejes: produkter og priser måske i dit ERP, ordrer i webshoppen, kunder i begge. Så ved du også, hvilken vej data skal flyde.

Beslut derefter, hvor hurtigt det skal gå. Lagerstatus på en populær vare skal måske være opdateret inden for minutter, mens en bogføring gerne må ske om natten. Realtid er dyrere og mere skrøbelig end en fast kørsel hvert kvarter, så vælg den kun, hvor det betyder noget. Og beslut, hvad der skal ske, når det andet system er nede: skal ordren stadig kunne gennemføres, og hvem får besked? Læs til sidst API’ets dokumentation for grænser for antal kald og for et testmiljø, så du ikke tester mod rigtige data.

Nøglerne bliver på serveren

En API-nøgle er et password. Kald et API, der kræver en nøgle, direkte fra browserens JavaScript, og nøglen ligger i koden, som enhver besøgende kan læse. Kaldet skal i stedet gå fra din server: browseren spørger din side, din side spørger API’et med nøglen, og kun svaret sendes videre. I WordPress ser et kald typisk sådan ud, med nøglen i wp-config.php og svaret gemt i en transient, så API’et ikke kaldes for hver besøgende:

// wp-config.php: define( 'FRAGT_API_KEY', '...' );

function clypper_fragtpriser() {
    $priser = get_transient( 'fragtpriser' );
    if ( false !== $priser ) {
        return $priser;
    }
    $svar = wp_remote_get( 'https://api.eksempel.dk/v1/priser', [
        'timeout' => 5,
        'headers' => [ 'Authorization' => 'Bearer ' . FRAGT_API_KEY ],
    ] );
    if ( is_wp_error( $svar ) || 200 !== wp_remote_retrieve_response_code( $svar ) ) {
        return []; // brug en standardpris, og log fejlen
    }
    $priser = json_decode( wp_remote_retrieve_body( $svar ), true );
    set_transient( 'fragtpriser', $priser, HOUR_IN_SECONDS );
    return $priser;
}

Giv nøglen så få rettigheder som muligt, fx kun læseadgang, hvis integrationen kun henter data. Tager du imod webhooks, så tjek signaturen på hver besked, så ingen andre kan sende falske ordrer eller statusopdateringer til din side.

Når API’et er langsomt eller nede

Et eksternt API er et andet firmas server, og den vil på et tidspunkt være langsom eller nede. Spørgsmålet er, om din side går ned med den. Det første værn er en kort timeout. WordPress venter som standard 5 sekunder, og mange plugins sætter den højere. Kaldes API’et under en sidevisning, venter den besøgende hele tiden, og alle PHP-processerne kan ende med at stå og vente på det samme svar.

Det andet værn er at undgå kald under sidevisningen overhovedet. Data, der ikke ændrer sig hvert sekund, som fragtpriser, produktdata og valutakurser, kan hentes i baggrunden og gemmes lokalt. Ordrer, der skal sendes videre, kan lægges i kø i et baggrundsjob, i WooCommerce typisk med Action Scheduler, så kunden får sin ordrebekræftelse, selvom økonomisystemet er nede, og ordren sendes, når det er oppe igen.

Fejler et kald, så prøv igen med stigende pauser, fx efter et, fem og tyve minutter, i stedet for at hamre løs. Sørg for, at det er sikkert at sende det samme to gange, så en genudsendt ordre ikke bliver bogført dobbelt; mange API’er understøtter en idempotency-nøgle til netop det. Og log hvert fejlet kald med tidspunkt, adresse og svar, men aldrig med nøglen eller kundens persondata. Kan det andet system sende webhooks, så brug dem frem for at spørge hvert minut, om der er nyt: det er både hurtigere og belaster begge sider mindre.

Vedligeholdelse

En integration er ikke færdig, når den virker. API’er får nye versioner, og gamle lukkes med nogle måneders varsel, som typisk sendes til den e-mail, der oprettede nøglen. Sørg for, at den e-mail bliver læst, at fejl i integrationen giver en besked til en person og ikke kun en linje i en log, og at nogen har ansvaret for at rette det, når det sker.

Ofte stillede spørgsmål

Kan jeg kalde et API direkte fra JavaScript i browseren?

Kun hvis API’et er offentligt og ikke kræver en hemmelig nøgle, fx et kort eller et åbent datasæt. Kræver det en nøgle, skal kaldet gå gennem din server.

Hvad koster en API-integration?

Et færdigt plugin kan koste en lille årlig licens. En egen integration afhænger af, hvor mange systemer og regler der er, og af API’ets kvalitet. Husk at regne vedligeholdelsen med, ikke kun udviklingen.

Hvad er forskellen på et API og en webhook?

Med et API spørger din side det andet system. Med en webhook sender det andet system selv en besked til din side, når noget sker, fx når en pakke er afsendt.

Vil du have hjælp?

Vi bygger integrationer mellem WooCommerce og økonomi-, lager- og fragtsystemer, og vi vedligeholder dem, når API’erne ændrer sig. Læs mere om integrationer og specialudvikling.