Udfyld et integrationsbrief med en rapportbestilling

Beskriv en integration gennem ét komplet forløb, før du sammenligner tilbud. “Portalen skal have en API-forbindelse” lader det stå åbent, hvilke data der overføres, hvornår arbejdet er færdigt, og hvem der håndterer en fejl. Et gennemarbejdet brief gør det muligt at drøfte beslutningerne.

Vælg ét forløb til den første leverance

I dette fiktive projekt skal en portal bestille en månedlig PDF-rapport hos en dokumenttjeneste. Alle navne, felter og svar er vores egne eksempler, ikke en leverandørs API.

Det gør også ekstra ønsker synlige: En senere e-mailfunktion bliver et selvstændigt trin med egen fejlhåndtering. Den forsvinder ikke ind i ordet “forbindelse”.

Angiv input med værdier og betydning

Følgende eksempelindhold aftales for POST /report-jobs:

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

Forespørgsels-ID'et betegner denne bestilling. Projekt og skabelon er stabile referencer; perioden er her en kalendermåned i formatet år–måned. Visningsnavne eller en periode beskrevet med fri tekst erstatter ikke værdierne. Portalen skal afklare med dokumenttjenesten, hvilke skabeloner der er godkendt.

Adgangen til opgave, status og fil begrænses til det autoriserede projekt. At kende et link giver ikke i sig selv ret til at hente filen. Roller og adgangsmetode hører til i briefet; rigtige tokens og adgangskoder holdes uden for dokumentet.

Beskriv modtagelse og resultat hver for sig

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

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

MDN beskriver 202 som accept af en behandling, der endnu ikke er afsluttet. Vores egen kontrakt har derfor tilstandene queued (venter), running (under behandling), succeeded (lykkedes) og failed (mislykkedes). Opgaven lykkes først, når filen er oprettet og på afslutningstidspunktet kan hentes med den rette adgang. Microsoft beskriver et særskilt statusopslag til asynkront arbejde; de konkrete tilstandsnavne her er vores valg.

Samme forespørgsels-ID med identisk indhold inden for samme autoriserede omfang henviser til samme opgave. Ved andet indhold aftaler eksemplet HTTP 409. Gentagelsesreglen skal implementeres og kontrolleres; feltnavnet skaber ikke i sig selv idempotens.

Udfyld fire accepttilfælde før implementering

I sidste tilfælde undersøger platformteamet skabelonen. En rettet ny bestilling får et nyt forespørgsels-ID; den mislykkede opgave forbliver sporbar. Er kun statusopslaget utilgængeligt, viser portalen, at den aktuelle tilstand er ukendt, og påstår hverken succes eller fejl.

Afklar åbne driftsspørgsmål før et løfte

Tilføj forventet opgavemængde, typisk filstørrelse, acceptabel ventetid, opslagets interval og opbevaring af filer og statusdata ud fra den faktiske brug. Værdierne er stadig åbne i eksemplet og skal afklares før et pålideligt løfte. En anslået varighed behandles ikke som en målt egenskab.

En OpenAPI-beskrivelse kan præcisere operationer, input og forventede svar. Den forretningsmæssige definition af resultatet og teamenes ansvar skal også fastlægges. Med de gennemarbejdede tilfælde kan portal- og platformteam derefter vurdere den samme leverance.

Kilder

• MDN: 202 Accepted

• Microsoft: Asynchronous Request-Reply pattern

• OpenAPI Specification 3.1.1: Operation and Responses