Skriv en integrationsbrief utifrån en rapportbeställning
Bestäm omfattning, exempeldata, svar och acceptansfall för en koppling mellan en projektportal och en dokumenttjänst.
Beskriv en integration genom ett komplett flöde innan du jämför offerter. ”Portalen behöver en API-koppling” lämnar öppet vilka data som överförs, när arbetet är klart och vem som hanterar ett fel. En genomarbetad brief gör besluten möjliga att diskutera.
Välj ett flöde för den första leveransen
I detta fiktiva projekt ska en portal beställa en månadsrapport som PDF från en dokumenttjänst. Alla namn, fält och svar är våra egna exempel, inte en leverantörs API.
Briefingfält | Överenskommelse i exemplet |
|---|---|
Mål | En behörig projektmedarbetare kan hämta den beställda månadsrapporten i portalen. |
Källa | Projektportalen skickar projekt, bekräftad rapportmånad och godkänd mallreferens. Portalteamet ansvarar för valet. |
Målsystem | Dokumenttjänsten skapar PDF-filen. Dess plattformsteam ansvarar för bearbetning och feltillstånd. |
Utlösare | En uttrycklig beställning i portalen; inget nytt jobb vid varje sidvisning. |
Leveransomfattning | Skapa ett jobb, fråga efter dess tillstånd och hämta den färdiga filen. |
Undantaget | Att skicka e-post och föra över alla historiska rapporter. |
Det synliggör också tillkommande önskemål: En senare e-postfunktion blir ett eget steg med egen felhantering. Den försvinner inte in i ordet ”koppling”.
Ange indata med värden och betydelse
Följande exempelinnehåll avtalas för POST /report-jobs:
{"requestId":"R-52","projectId":"P-18","templateId":"monthly-v2","period":"2026-10"}Begärans ID betecknar denna beställning. Projekt och mall är stabila referenser; perioden är här en kalendermånad i formatet år–månad. Visningsnamn eller en period i fritext ersätter inte värdena. Portalen måste klargöra med dokumenttjänsten vilka mallar som är godkända.
Åtkomst till jobb, tillstånd och fil begränsas till det behöriga projektet. Att känna till en länk ger inte i sig rätt att hämta filen. Roller och åtkomstmetod hör hemma i briefen; riktiga token och lösenord hålls utanför dokumentet.
Beskriv mottagande och resultat var för sig
Efter beständig registrering svarar exempeltjänsten med HTTP 202 och Location: /report-jobs/J-52:
{"jobId":"J-52","status":"queued"}MDN beskriver 202 som att en ännu inte avslutad bearbetning har accepterats. Vårt eget kontrakt har därför tillstånden queued (väntar), running (bearbetas), succeeded (lyckades) och failed (misslyckades). Jobbet lyckas först när filen har skapats och vid avslutstillfället kan hämtas med rätt behörighet. Microsoft beskriver en separat statusförfrågan för asynkront arbete; de konkreta tillståndsnamnen här är vårt val.
Samma begärans-ID med identiskt innehåll inom samma behörighetsomfattning hänvisar till samma jobb. Vid avvikande innehåll används HTTP 409 i exemplet. Upprepningsregeln måste implementeras och kontrolleras; fältnamnet skapar inte i sig idempotens.
Formulera fyra acceptansfall före implementeringen
Fall | Förväntat resultat |
|---|---|
Giltig beställning | Mottagande, synligt förlopp och till slut en rapport som kan hämtas för avtalat projekt och avtalad månad. |
Mallreferensen saknas | HTTP |
Svaret på en mottagen beställning försvinner | Upprepning med samma innehåll och begärans-ID hittar det befintliga jobbet; ingen andra rapportkörning. |
Mallen tas bort efter mottagandet | Bearbetningen slutar med |
I det sista fallet kontrollerar plattformsteamet mallen. En rättad ny beställning får ett nytt begärans-ID; det misslyckade jobbet förblir spårbart. Om bara statusförfrågan är otillgänglig visar portalen att det aktuella tillståndet är okänt, utan att hävda framgång eller misslyckande.
Red ut öppna driftfrågor innan du ger ett löfte
Lägg till förväntad jobbmängd, typisk filstorlek, acceptabel väntetid, frågeintervall samt lagringstid för filer och statusdata utifrån den faktiska användningen. Värdena är fortfarande öppna i exemplet och måste klargöras före ett tillförlitligt löfte. En uppskattad tid behandlas inte som en uppmätt egenskap.
En OpenAPI-beskrivning kan precisera operationer, indata och förväntade svar. Även verksamhetens definition av resultatet och teamens ansvar måste fastställas. Med de konkreta fallen kan portal- och plattformsteam sedan bedöma samma leverans.
Källor
Läs vidare
Alla artiklar
API:er & integration med ASES
ERP, CRM och webbutik smidigt sammankopplade