Vi versjonerer på URL. Domenenavn og ressurs vil være det samme for nytt og gammelt API, men versjonsnummer (siste parameter i URL) vil differensiere versjon.
VIKTIG DISTINKSJON: Vi kan ikke bryte API-kontrakten med konsumentene for Minor og Errata. Dette leses under fra føringene for utforming av eksterne API for Grunndata-tjenester / Persontjenesten:
Begrepet "non-breaking-changes" betegner endringer i grensesnittet (API funksjonalitet) eller FHIR datamodell som kan konsumeres av en eksisterende klient uten at klienten gjør endringer på sin implementasjon
- Ved ny versjon av et eksisterende API (Minor/Errata) - endres backend i API-konfigurasjonen i Azure API Management (ny versjon av API på ny pod, gammel pod/image beholdes temporært for å sikre rollback-muligheter)
- Vi godtar samme bearer-token fra HelseID
- Kontrakten opprettholdes med konsumentene (ellers er det ikke en Minor/Errata)
- Vi får på denne måten overført samtlige klienter til nyeste versjon, uten at de trenger å gjøre endringer på sin side (dette følges av føringene i kapittelet under - parafrasert: "ny funksjonalitet medfører ikke krav til å bruke den")
- Gammel "Minor/Errata" versjon tidsbegrenses IKKE, den ruller KONTINUERLIG videre med kort bakoverkompatibilitet / rollback-mulighet
- Ved Major - endringer som må anses som "breaking changes" og potensielt bryter bakoverkompatibilitiet, legges det opp ny versjon i Microsoft Azure API Management
- Vi krever et eget audience og scope i bearer-token for ny versjon
- Ny versjon gis versjonsnummer iht nummereringsstandard (marketing/arkitekt?)
- API versjoneres på URL (path) https://eksempelapi.helsepunkt.no/persontjenesten/v2 ... Konsumenter varsles om at API må byttes fra gammelt til nytt API hos konsument innen gitt grace-period (eksempelvis "12 måneder fra nytt API oppstår") Gammelt API tidsbegrenses etter spesifikasjon fra API-eier Det må bestemmes om noen versjon av et API skal ha forlenget levetid, eksempelvis første versjon Nytt API skal gå gjennom tre faser: Innfasing - "Produksjon" - Utfasing
- Det vil til enhver tid til være minst 3 versjoner av et API tilgjengelig, som tegningen over viser
- Dersom endring skjer i kontrakten, som medfører breaking change / Major versioning, så må versjon fremskyndes.
- Tegningen tar høyde for ny versjon per år - må kun anses som eksempel og skal ikke være styrende. API-eier bestemmer release cycle.
- Det er en forutsetning at EPJ-leverandører utvikler løsning for å kunne konsumere nytt API, og inkluderer i sin årlige patch/release av EPJ-systemet
- Dette fordrer en dialog mellom kunde/MF Helse/EPJ leverandør
Endringer i API kan forårsakes av et utall forskjellige grunner, som er vanskelig å forutse uten erfaringsbase. Enkelte er lette å identifisere som Major (slik som "Erstatte FHIR server), mens feilretting av datamodellen kan utløse Major/Minor/Errata. Endringer i API må/bør gå gjennom et changeboard (ref. ITIL) som avgjør hvilken type endring som skal adresseres, og hva slags impact dette vil ha.
Major-versjoner trenger ikke nødvendigvis følge FHIR-versjoner (merk - det er ikke en 1:1 relasjon mellom FHIR-versjon og API-versjon - eventuelle like versjonsnummer er å anse som tilfeldigheter):
Potensielle endringer som kan/vil forårsake major/minor/errata (ikke detaljert):
- Nye data / Ny datakilde
- Feilretting i datamodellen
- Feiltolkning av data
- Det vi fikk var noe annet enn det vi trodde vi skulle få
- Oppgradering av Vonk-versjonen, f.eks. fra 3.1.1 til 3.1.3 (skrevet april 2020, kan være fullstendig utdatert når dette leses)
- Erstatte FHIR-server, f.eks. fra Fire.ly Vonk til Microsoft FHIR-server
- Definere nye FHIR-profiler på errata-nivå, f.eks. fra v4.0.0 til v4.0.1
- Release nye versjoner av Vonk-plugins (dataminimerings- og autentiserings plugins) som kan påvirke funksjonaliteten for sluttkonsumentene