Integration API — drift, feil og sporbarhet¶

Feilflyt¶

flowchart TD
  request["Request"] --> auth{"Autentisering OK?"}
  auth -- "Nei" --> authError["401 eller 403"]
  auth -- "Ja" --> validation{"Input gyldig?"}
  validation -- "Nei" --> bad["400 + ApiResponse"]
  validation -- "Ja" --> operation["Fagoperasjon"]
  operation --> expected{"Tjenesten håndterer feil?"}
  expected -- "Ja" --> safe["ApiResponse med sikker melding<br/>og ev. ErrorCode"]
  expected -- "Nei" --> middleware["Exception middleware"]
  middleware --> mapped{"Unntakstype"}
  mapped --> client["400, 401 eller 500"]
  safe --> logs["Serilog"]
  client --> logs

ErrorCode har format ERR-XXXXXXXX og kan brukes til å korrelere klientfeilen med serverloggen. Ikke alle controller-feil genererer en slik kode.

Statuskoder¶

Status	Typisk betydning
200	Operasjonen ble behandlet; kontroller også `Success`, `Data` og melding
400	Ugyldig modell, parameter, forretningsregel eller tjenestefeil
401	Manglende API-nøkkel/JWT eller en `UnauthorizedAccessException` i exception-middlewaren
403	Ugyldig v1-nøkkel, manglende claim eller tenant/client-mapping
404	Ressursen ble ikke funnet på endepunkter som skiller dette fra 400
500	Uhåndtert feil eller feil under OAuth-behandling/databaseoppslag

Logging¶

flowchart LR
  event["Logghendelse"] --> level{"Nivå"}
  level --> file["Rullerende fil/console"]
  level -- "Warning eller høyere" --> sql["ApiErrorLog i loggdatabasen"]
  request["Request/response"] --> payload{"Payload logging aktiv?"}
  payload -- "Ja" --> body["Logg body med størrelsesgrense"]
  payload -- "Nei" --> skip["Kun ordinær logging"]

Kanal	Innhold	Viktig
Ordinær Serilog	Oppstart, fagoperasjoner, warnings og exceptions	Produksjonskonfigurasjonen har minimum Warning
`ApiErrorLog`	Warning og høyere når `ConnectionStringLog` er satt	Batch på opptil 50 hendelser eller 10 sekunder
Payload-logg	Request- og response-body	Deaktivert i produksjonslogging som standard
Console	Miljøavhengig	Brukes av plattformens logginnsamling

Auth-headere og cookies maskeres. Payload-body maskeres ikke automatisk og kan inneholde personopplysninger. Aktiver derfor payload-logging bare tidsavgrenset og med avklart tilgang og retention.

Migrasjonen for ApiErrorLog oppretter en SQL Agent-jobb som sletter rader eldre enn 90 dager. Verifiser at både tabellen og jobben faktisk finnes i det aktuelle miljøet; migrasjonsfilen alene er ikke bevis på deploy.

Health og Swagger¶

Swagger registreres før auth-middlewarene og kan derfor lastes uten X-API-Key i applikasjonen. Ytre Basic Auth eller nettverksregler kan fortsatt beskytte produksjonsadressen.
/health er definert som et enkelt health-svar, men dagens ApiKeyMiddleware unntar bare /api/v2. Et kall til /health uten X-API-Key blir derfor fanget av v1-middlewaren. Overvåkning må enten sende en nøkkel eller implementasjonen må korrigeres.
Request/response-loggeren hopper over /health og /swagger.

Feilsøkingsrekkefølge¶

Noter UTC-tid, URL, metode, HTTP-status og ErrorCode.
Kontroller API-versjon og auth-header.
For v2: dekod token lokalt og kontroller aud, iss, exp, tid og azp/appid. Del aldri selve tokenet.
Kontroller aktiv rad i wv_OAuthTenantMapping eller v1-oppslaget i wv_Domain.
Vent ut eller tøm 30-minutters tenant-cache når mapping nylig er endret.
Finn ErrorCode eller tidspunkt i ordinær logg og ApiErrorLog.
Kontroller kundedatabase, lagret prosedyre og eventuelt ERP-oppslag.
Ved batch: finn nøyaktig hvilke elementer som feilet før retry.

Kjente kontraktsnyanser¶

Vanlige controller-responser og exception-responser bruker forskjellig casing på JSON-feltene.
Flere controllere fanger exceptions selv og returnerer generisk 500 uten ErrorCode.
Enkelte Accounting-endepunkter svarer 200 uten persistens.
Query-parametre på enkelte GET-ruter kan gi sideeffekt, blant annet markering av hentede arbeidsordrekostnader.

Kildepunkter¶

ePortalIntegrationApi/Middleware/ExceptionHandlingMiddleware.cs
ePortalIntegrationApi/Middleware/RequestResponseLoggingMiddleware.cs
ePortalIntegrationApi/Utilities/ErrorHelper.cs
ePortalIntegrationApi/Program.cs
ePortalIntegrationApi/appsettings.Logging.json
ePortalIntegrationApi/appsettings.Production.Logging.json
Database/Migration_Add_ApiErrorLog.sql