Hopp til hovedinnhold
NHN

Prinsipper for versjonering av Persontjenesten.

Grunnprinsipper

Persontjenesten legger ut nye versjoner som differensieres på URL. Domenenavn og ressurs vil være det samme for nytt og gammelt API, men versjonsnummer (siste parameter i URL) vil differensiere versjon.

Føringer for utforming av eksterne API for Persontjenesten. Vi planlegger at gjeldende versjoner skal være tilgjengelig for konsumenter i en gitt tidsperiode, som tegningen under viser.

Versjonering.jpeg
  • Tegningen tar høyde for ny versjon hvert år, men må kun anses som eksempel og vil ikke være styrende. Tidsfrekvens for release av versjoner er ikke endelig besluttet
  • Det er en forutsetning at EPJ-leverandører utvikler løsning for å kunne konsumere nytt API, og inkluderer dette i sin årlige patch/release av EPJ-systemet

Endringer: Breaking og non-breaking changes

Endringer i API kan forårsakes av et utall forskjellige grunner, som er vanskelig å forutse uten erfaringsbase. Enkelte er lette å identifisere som "breaking change", eller Major (slik som "Erstatte FHIR server"). Mindre endringer (Minor) omtaler vi som "non-breaking change". Feilretting av datamodellen kan utløse både Major og Minor endringer.

Endringer ved Major-versjon, "Breaking change"

Breaking-change betegner endringer i grensesnittet (API-funksjonalitet) eller FHIR datamodell som ikke kan konsumeres av en eksisterende klient uten at klienten gjør endringer på sin implementasjon, for eksempel:

  • Store endringer i informasjonsmodellen fra minst en kilde i løsningen (f.eks. FREG)
  • Ny hovedversjon av HL7 FHIR (R4, R5, osv.)
    • Major-versjoner vil ikke følge FHIR-versjoner (det er ikke en 1:1 relasjon mellom FHIR-versjon og API-versjon – eventuelle like versjonsnummer er å anse som tilfeldigheter)
  • Tekniske korrigeringer som kan ha forårsaket endringer i betydningen av enkelte attributter i modellen

Ved endringer som må anses som "breaking changes" og potensielt bryter bakoverkompatibilitet, legges det opp ny versjon:

  • Persontjenesten krever eget scope i sikkerhetsbilletten for ny versjon. Scope kan ses som en beskrivelse av hvilke rettigheter man har mot API-et
  • Ny versjon gis versjonsnummer i henhold til nummereringsstandard
  • API versjoneres på siste ledd i URL: …no/persontjenesten/v2
  • Konsumenter varsles om at API må byttes fra gammelt til nytt API hos konsument innen en gitt overgangsperiode (eksempelvis "12 måneder fra nytt API oppstår")
  • Nytt API skal gå gjennom tre faser: Innfasing – Produksjon – Utfasing
    • Innfasing: API testes på utvalgte utprøvingskandidater.
    • Produksjon: Alle konsumenter tilbys tilgang til API.
    • Utfasing: API opprettholdes ut en bestemt periode. Feilretting vil ikke utføres på et utfaset API.

Endringer ved Minor-versjon, "Non-breaking change"

Begrepet "non-breaking-changes" (Minor) betegner endringer i grensesnittet (eksisterende API) eller FHIR datamodell som kan konsumeres av en eksisterende klient uten at klienten gjør endringer på sin implementasjon. Samtlige klienter vil bli sømløst overført til nyeste versjon på Minor-nivå, uten at de trenger å gjøre endringer på sin side (ny funksjonalitet medfører ikke krav til å bruke den).

  • Oppdateringer i dokumentasjonen som klargjør funksjonaliteten i grensesnittet eller forklarer hvordan datamodellen skal tolkes
  • Det kan legges til API-funksjonalitet til grensesnittet (nye søkeparametere eller operasjoner kan implementeres) som et tilbud, men ikke et krav, til konsumenter om å benytte ny funksjonalitet
  • Det kan legges informasjon i eksisterende informasjonselementer i datamodellen, hvis informasjon blir tilgjengelig i tjenesten og informasjonsinnholdet ikke avviker fra datamodellen
  • Ingen tidsbegrensning på Minor-nivå, følger Major-release
  • Estimert én oppdatering hvert år
  • Typisk endringer i informasjonsmodellen som ikke berører andre deler av modellen. Eksempel:
    • Berikelse av informasjonsmodellen
    • Tekniske justeringer ved oppgradering av bakenforliggende infrastruktur som ikke skal påvirke betydning av attributter i modellen

Sikring av tilgangen for API-tjenester

Tilgang til samtlige tjenester skal være sikret ved bruk av styringsmekanismer i HelseID. Det skal være definert en utløpsdato for tilgang til utgått API, og det vil ikke være mulig å benytte utgått API etter denne dato. Det vil ikke tildeles nye tilganger til et utgått API.

HelseID er en nasjonalt tiltrodd tredjepart som ivaretar sikkerhetsbehov i digital samhandling mellom virksomheter i helsesektoren. Alle aktører som skal ta i bruk API-tjenester fra Persontjenesten må være autentisert via HelseID (maskin-til-maskin-tilkobling)

Les mer om bruk av HelseID for å få tilgang til Persontjenesten.