Typesikker og effektiv API-integrasjon

Skriver du manuelt typer for request, respons og data-body til API-endepunkt i Typescript? Det trenger du ikke lenger!

Dersom du skal hente eller sende data til et API som følger OpenAPI-spesifikasjonen kan du nå ved hjelp av pakkene openapi-typescript og openapi-fetch få:

✅ Unngå skrivefeil i URL og parametre

✅ Alle parametre, data-body og respons er type-sjekket og stemmer nøyaktig med ditt API

✅ Autocomplete på endepunkt, path's, query parametre, data-body, requests og respons

✅ En enkel og effektiv API-klient

Forarbeid

Oppsettet krever at API'et du skal kommunisere med er satt opp med OpenAPI-spesifikasjon.

Les mer her: https://swagger.io/solutions/getting-started-with-oas/

Har du laget API'et med .NET Core og ønsker du at endepunktene blir generert med lowercase? Da kan du legge på en routing-option i API'et.

// Gjøre i Program.cs
builder.Services.AddRouting(options => options.LowercaseUrls = true);

Generer klient-kode

Når API'et har OpenAPI satt opp er du klar!

Vanlig praksis er å lage script for generering basert på lokalt API i tillegg til å generere fra dev eller testmiljø.

// package.json under scripts
"generate-types:local": "npx openapi-typescript http://localhost:5000/openapi/v1.json -o ./src/generated-api-client/schema.d.ts",
"generate-types:dev": "npx openapi-typescript https://dev.api.julekalender.kraftlauget.no/openapi/v1.json -o ./src/generated-api-client/schema.d.ts",

Dersom du har et standard Prettier-oppsett kan du bruke opsjonen "--prettier-config [location]" for å formattere, men om du bruker Prettier i kombinasjon med eslint i en Nextjs-applikasjon er erfaringen at du må kjøre prettier direkte etter kodegenerering.

"generate-types:local": "npx openapi-typescript http://localhost:5000/openapi/v1.json -o ./src/generated-api-client/schema.d.ts && npx prettier --write ./src/generated-api-client/schema.d.ts"

Kjør "npm run generate-types:local" og mappen generated-api-client blir opprettet med schema-filen.

Eksempel på bruk av fetch-klient

Her vil vi få typede endepunkt, request, response, path og queries, som gjør at du vil oppdage feil som ellers kunne lurt seg med.

import createClient from "openapi-fetch"; // Fetch client
import type { paths } from "./schema"; // Generert av openapi-typescript

const client = createClient<paths>({ baseUrl: "https://api.julekalender.kraftlauget.no/v1" });

const { data, error } = await client.GET("/luke/{luke_id}", {
    params: {
        path: { luke_id: "13" },
    },
    cache: 'no-store', // Eksempel med Nextjs cache
});

const { data, error } = await client.POST("/luke", {
    body: {
        title: "Ny luke",
        body: "<p>Ny luke</p>",
        publish_date: new Date("2024-12-13T12:00:00Z").getTime(),
    },
});

Eksempel på bruk av typer

import type { paths, components } from "./schema"; // Generert av openapi-typescript

// Schema typer
type Luke = components["schemas"]["Luke"];

// Path params
type LukeParams = paths["/luke"]["parameters"];

// Response obj
type LukeSuccessResponse =
paths["/luke"]["get"]["responses"][200]["content"]["application/json"]["schema"];

Oppsummering

Oppsettet gjør at du potensielt kan spare deg for bugs som fanges opp av typesjekken og at du kan få gjort endringer raskere ved å kjøre generering på nytt og fikse evt. kompileringsfeil. I tillegg er det praktisk å bruke de genererte typene i mappere for å kunne returnere applikasjonsspesifikke typer.

--

Les mer om openapi-typescript i lenken under:

https://github.com/openapi-ts/openapi-typescript