Fyll ut en integrasjonsbrief med en rapportbestilling

Beskriv en integrasjon gjennom ett komplett forløp før du sammenligner tilbud. «Portalen trenger en API-kobling» lar det stå åpent hvilke data som overføres, når arbeidet er ferdig, og hvem som håndterer en feil. En utfylt brief gjør beslutningene mulige å diskutere.

Velg ett forløp til den første leveransen

I dette fiktive prosjektet skal en portal bestille en månedlig PDF-rapport fra en dokumenttjeneste. Alle navn, felt og svar er våre egne eksempler, ikke en leverandørs API.

Dette gjør også tilleggsønsker synlige: En senere e-postfunksjon blir et eget trinn med egen feilhåndtering. Den forsvinner ikke inn i ordet «kobling».

Oppgi inndata med verdier og betydning

Følgende eksempelinnhold avtales for POST /report-jobs:

{"requestId":"R-52","projectId":"P-18","templateId":"monthly-v2","period":"2026-10"}

Forespørsels-ID-en betegner denne bestillingen. Prosjekt og mal er stabile referanser; perioden er her en kalendermåned i formatet år–måned. Visningsnavn eller en periode skrevet som fritekst erstatter ikke verdiene. Portalen må avklare med dokumenttjenesten hvilke maler som er godkjent.

Tilgang til jobb, status og fil begrenses til det autoriserte prosjektet. Å kjenne en lenke gir ikke i seg selv rett til å laste ned. Roller og tilgangsmåte hører hjemme i briefen; faktiske tokener og passord holdes utenfor dokumentet.

Beskriv mottak og resultat hver for seg

Etter varig registrering svarer eksempeltjenesten med HTTP 202 og Location: /report-jobs/J-52:

{"jobId":"J-52","status":"queued"}

MDN beskriver 202 som aksept av en behandling som ennå ikke er avsluttet. Vår egen kontrakt har derfor tilstandene queued (venter), running (under behandling), succeeded (lyktes) og failed (mislyktes). Jobben lykkes først når filen er opprettet og på fullføringstidspunktet kan hentes med riktig tilgang. Microsoft beskriver et eget statusoppslag for asynkront arbeid; de konkrete tilstandsnavnene her er vårt valg.

Samme forespørsels-ID med identisk innhold innenfor samme autoriserte omfang viser til samme jobb. Ved avvikende innhold avtaler eksemplet HTTP 409. Gjentakelsesregelen må implementeres og kontrolleres; feltnavnet skaper ikke i seg selv idempotens.

Fyll ut fire akseptansetilfeller før implementering

I det siste tilfellet undersøker plattformteamet malen. En rettet ny bestilling får en ny forespørsels-ID; den mislykkede jobben forblir sporbar. Er bare statusoppslaget utilgjengelig, viser portalen at den aktuelle tilstanden er ukjent, og påstår verken suksess eller feil.

Avklar åpne driftsspørsmål før et løfte

Legg til forventet jobbmengde, typisk filstørrelse, akseptabel ventetid, oppslagsintervall og lagringstid for filer og statusdata ut fra faktisk bruk. Verdiene er fortsatt åpne i eksemplet og må avklares før et pålitelig løfte. En anslått varighet behandles ikke som en målt egenskap.

En OpenAPI-beskrivelse kan presisere operasjoner, inndata og forventede svar. Den forretningsmessige definisjonen av resultatet og teamenes ansvar må også fastsettes. Med de gjennomarbeidede tilfellene kan portal- og plattformteam deretter vurdere samme leveranse.

Kilder

• MDN: 202 Accepted

• Microsoft: Asynchronous Request-Reply pattern

• OpenAPI Specification 3.1.1: Operation and Responses