Fælles retningslinjer for webservices...Webservices skal have en entydig mekanisme til ansvarsoverdragelse mel-lem myndigheder, således at der altid er klarhed over, hvilken myndighed

Fælles retningslinjer for webservices

UDKAST version 0.9

December 2017

Indhold

1. Indledning 3

1.1 Afgrænsning 4

1.2 Læsevejledning 4

1.3 Oversigt over retningslinjer 6

2. Principper og forretningsbehov for retningslinjer 8

3. Generelle retningslinjer for webservices 11

3.1 Fokus på serviceanvendere 11

3.2 Ansvarsfordeling ved kald til webservices 14

3.3 Servicedokumentation 15

3.4 Serviceversionering 20

3.5 Servicelogning 22

3.6 Servicetilgængelighed 24

3.7 Servicefejlmeddelelser 25

3.8 Temporale ressourcer 27

3.9 Sikkerhedskrav til webservices 33

4. Retningslinjer for REST webservices 34

4.1 Modellering af REST webservices 34

4.2 Søgninger i REST webservices 40

4.3 Datarepræsentation i REST webservices 42

4.4 REST kommunikationsprotokol 45

4.5 Sikkerhedskrav til REST webservices 47

5. Referenceliste 49

6. Appendiks A Eksempel på anvendelse 50

6.1 Avendelse af temporalitet 51

7. Appendiks B Liste over retningslinjer: 53

Side 3 af 54

1. Indledning

Dette dokument beskriver fællesoffentlige retningslinjer for anvendelse af web-

services og særligt REST (Representational State Transfer) webservices i it-

løsningerne i den offentlige sektor. Formålet med de fælles retningslinjer for

webservices er at skabe bedre interoperabilitet imellem offentlige institutioners

it-løsninger.

Retningslinjerne er udsprunget af ”Hvidbog om arkitektur for digitalisering” (jf.

[HVIDBOG]), hvor retningslinjerne er en konkretisering af princip 7 og arkitek-

turregel 7.1 . Princip 7 tilsiger, at it-løsninger samarbejder effektivt, mens arkitek-

turregel 7.1 tilsiger, at der skal designes og udstilles snitflader efter fælles integra-

tionsmønstre og tekniske standarder

De fælles retningslinjer for webservices i dette dokument er en vejledning til ser-

viceudbydere, der skal udstille data og funktionalitet via webservices. Vejlednin-

gen skal opfattes som en beskrivelse af god praksis og skal hjælpe serviceudbyde-

ren, når denne designer og udstiller webservices rettet imod serviceanvendere.

En række domæner har i dag allerede domænespecifikke retningslinjer og stan-

darder, fx på sundhedsområdet. Det er væsentligt, at anvendelsen af retningslin-

jerne finder sted i samspil med eksisterende retningslinjer og standarder, således

at der ikke skabes unødig kompleksitet. De fælles retningslinjer er særligt anven-

Definitioner:

Webservices er defineret som angivet i [W3C]: “A Web service is a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-processable format (specifically WSDL)” ”We can identify two major classes of Web services:

o REST-compliant Web services, in which the primary pur-pose of the service is to manipulate XML representations of Web resources using a uniform set of "stateless" opera-tions; and

o arbitrary Web services, in which the service may expose an arbitrary set of operations.“

REST er en arkitekturstil, der anvendes til udstilling af ressourcer (data) med webservices. REST er baseret på principperne og arki-tekturen, som anvendes på internettet, og genbruger få, udbredte standarder og protokoller herfra, f.eks. HTTP. [ FIELDING].

Side 4 af 54

delige, hvor der ikke foreligger domænespecifikke standarder og retningslinjer

for webservices.

1.1 Afgrænsning

Retningslinjerne har følgende væsentlige afgrænsninger:

Retningslinjerne stiller ikke krav til, at offentlige institutioner skal anven-de REST over andre arkitekturstile, når data og funktionalitet skal udstil-les via webservices.

Serviceanvendere kan have behov for at kalde mere end én webservice. Et eksempel herpå er en serviceanvender, som skal foretage en opdate-ring i to it-løsninger via to forskellige webservices. Sådanne situationer er omfattet af begrebet ”serviceorkestrering”, der inkluderer kald af flere services. Retningslinjerne i dette dokument omfatter ikke serviceorkestre-ring, da det indeholder designvalg omkring processer og orkestrering, som ikke er en del af retningslinjernes område.

Retningslinjerne stiller ikke krav om hvornår temporaler generelt skal an-vendes i webservices, dette er serviceudstillers beslutning, retningslinjer stiller således kun krav til hvordan webservices udstiller temporaler.

Retningslinjerne stiller krav til logning i forbindelse med webservicens anvendelse, og dokumentet indeholder ikke retningslinjer, som sikrer overholdelse af bestemt lovgivning, fx GDPR.

Retningslinjerne i dette dokument kan den enkelte organisation vælge at anvende inden for egen organisation for at skabe mere ensartede snitfla-der på tværs af it-løsninger, men det er ikke et krav.

1.2 Læsevejledning

Dokumentet er opbygget i fem hovedafsnit.

Nærværende afsnit 1 udgør en kort indledning.

Afsnit 2 indeholder en redegørelse for de principper og forretningsbe-hov, der ligger til grund for de angivne retningslinjers udformning.

Afsnit 3 indeholder angivelse af generelle retningslinjer, der skal anven-des af webservices og kan være anvendelige for alle. Retningslinjerne er grupperet efter tema, således at retningslinjerne hurtigt kan identificeres ud fra læserens behov.

Afsnit 4 indeholder en angivelse af retningslinjer, der er specifikke for REST webservices.

Afsnit 5 indeholder en referenceliste.

Afsnit 6 indeholder et tværgående eksempel.

Dokumentet henviser til følgende bilag:

Side 5 af 54

Bilag 1 ”Dokumentation for REST Webservices” Bilaget giver uddyben-de beskrivelse af retningslinje R06.

Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices” omhandler ensretning af fejlstrukturer for webservices og ensartet anvendelse af HTTP headers og håndtering af asynkrone kald.

Bilag 3 ”Nonfunktionelle krav til realisering af retningslinjer” indeholder et kravbilag, som kan anvendes af serviceudbydere til at kravstille web-services, som overholder retningslinjerne.

Bilag 4 ”Specifikation for brug af HTTP til REST” uddyber mere detalje-ret anvendelsen af REST over HTTP. REST giver stor mulighed for fleksibilitet i udarbejdelsen af snitfladen, men bilagets formål er at skabe større ensartethed på almindeligt udstillet funktionalitet.

Side 6 af 54

1.3 Oversigt over retningslinjer

Dokumentet indeholder følgende retningslinjer opdateret efter tema.

Generelle retningslinjer for webservices

Fokus på serviceanvendere

R01. Udstil minimal funktionalitet og data i den enkelte webservice

R02. Separér webservices fra konkret implementering

R03. Separér webservices fra eksterne afhængigheder

Ansvarsfordeling ved kald til webservices

R04. Understøt gentagne forsøg på kald fra serviceanvenderen

R05. Kræv specifikkke informationer ved ansvarsoverdragelse ved kald til web-services

Servicedokumentation

R06. Dokumentér udstillede webservices i overensstemmelse med den fællesof-fentlige dokumentationsramme for webservices

R07. Opmærk webservices i henhold til fællesoffentlige emnesystematikker

R08. Opmærk webservices med følsomhed eller fortrolighed af data

R09. Dokumentér servicespecifikke fejlkoder for webservices

R10. Dokumentér drift af forskellige versioner af webservices

Serviceversionering

R11. Anvend semantisk versionering af webservices

R12. Viderefør gamle versioner, når en webservice ændres

Servicelogning

R13. Log alle kald til webservices

R14. Anvend transaktionsidentifikatorer ved kald og svar

R15. Anvend requestID ved kald og svar

Servicetilgængelighed

R16. Understøt monitorering af udstillede webservices

Servicefejlmeddelelser

R17. Returnér servicespecifikke fejl som standardiserede fejlmeddelelser

Temporale ressourcer

R18. Forretningsregler vedrørende temporaler indkapsles og håndhæves på ser-viceniveau

R19. Webservices med temporale ressourcer returnerer som et øjebliksbillede

R20. Webservices med temporale ressourcer anvender anerkendte nøgleord i søgeparametre.

R21. Webservices med temporale ressourcer skal udstille ensartet funktionalitet til revision og Linje

R22. Webservices med temporale ressourcer skal anvende ens håndtering af tidspunkter

Sikkerhedskrav til webservices

R23. Webservices skal have tokenbaseret sikkerhed

Side 7 af 54

Retningslinjer for REST webservices

Modellering af REST webservices

R24. Udstil webservices som REST ressourcer

R25. Udstil data som REST ressourcer

R26. Modellér REST ressourcer med udgangspunkt i forretningsmodellering

R27. Navngiv REST ressourcer ud fra forretningsmodellens begreber

R28. Navngiv REST ressourcer ud fra REST arkitekturstilen

R29. Udstillede REST ressourcer har unikke, sikre identifikatorer

R30. Udstil REST ressourcers relaterede entiteter

R31. Returnér REST ressourcer med hypertext links

Søgninger i REST webservices

R32. Anvend standardiserede REST fremsøgningsparametre

R33. Understøt søgning med delresultater

Datarepræsentation i REST webservices

R34. Repræsentér REST ressourcer i et standardiseret dataformat

R35. Deklarér REST ressourcer datarepræsentationer

R36. Overfør tekst i en internationaliseret repræsentation

REST kommunikationsprotokol

R37. Anvend HTTP som fællesoffentlig REST kommunikationsprotokol

R38. Anvend HTTPs mekanismer til effektiv kommunikation

R39. Anvend HTTP sikkert til REST ressourcer

Sikkerhedskrav til REST webservices

R40. REST webservices skal anvende OIO IDWS REST profile V1.0

Retningslinjerne beskrives efter følgende mønster:

Navn Angiver nummeret og navnet på retningslinjen Retningslinje Beskriver retningslinjen klart og præcist

Rationale Beskriver forretningsværdien ved at følge retningslinjen

Understøttede forret-ningsbehov

Beskriver de konkrete forretningsbehov, som retningslinjen understøtter

Implikation Beskriver hvilken indvirkning, retningslinjen har på forret-ningsmæssig og teknisk implementering

Før beskrivelsen af hver retningslinje kan der være en kort indledning, der for-

klarer baggrunden for retningslinjen. Denne indledning anses ikke som en del af

retningslinjen, men skal blot give læseren yderligere viden, kontekst og baggrund

for at forstå den pågældende retningslinje.

Side 8 af 54

2. Principper og forretningsbehov for

retningslinjer

Retningslinjerne for webservices er udarbejdet med henblik på at være bredt

anvendelige i den offentlige sektor. Retningslinjerne er baseret på praktisk erfa-

ring, samt målrettet anvendelse i realiseringen af Hvidbog om arkitektur for digi-

talisering. Anvendeligheden sikres ved specificering af tre overordnede princip-

per samt en række forretningsbehov, som retningslinjerne udmønter. Principper

og forretningsbehov i dette afsnit har således udgjort grundlaget for udarbejdel-

sen af retningslinjerne, der fremgår af afsnit 3 og 4.

Den organisation, som ønsker at anvende retningslinjerne, bør undersøge, om

organisationen har forretningsbehov, der adskiller sig væsentligt fra de her anfør-

te forretningsbehov. Hvis dette er tilfældet, kan organisationen overveje, hvor-

vidt snitfladerne skal udarbejdes efter retningslinjerne. Tilsvarende kan det være

nødvendigt, at den pågældende organisationen tager stilling til, hvilke forret-

ningsbehov, der er vigtigst.

Principper

Følgende tre principper gælder for alle retningslinjerne:

Retningslinjerne skal kunne anvendes bredt af offentlige institutioner, samt andre organisationer der ønsker at anvende dem.

Retningslinjerne skal baseres på viden fra anvendelser af eksisterende retningslinjer for webservices, bl.a. fra SKAT, Sundhedsdatastyrelsen, Grunddataprogrammet, KOMBIT m.fl.

Retningslinjerne skal være langtidsholdbare, men samtidig være tilstræk-keligt konkrete og implementeringsnære til, at retningslinjerne kan ind-drages af initiativerne i digitaliseringsstrategien.

Forretningsbehov er opdelt i tre overordnede temaer.

Tema 1: Forretningsbehov vedrørende serviceanvendere og serviceudby-

dere

Temaet addresserer dilemmaet i at designe services, der er bedst for både ser-

viceanvendere og serviceudbydere. Retningslinjerne sætter fokus på, at service-

udbydere prioriterer servicenanvendernes behov og har et udefra-og-ind per-

spektiv, når webservices skal designes. Dermed menes, at serviceudbyder forstår

formålet med webservicen fra serviceanvenderens perspektiv.

F1. Webservices skal være omkostningseffektive set i et fællesoffentligt per-spektiv, således at der er fokus på totalomkostningen for serviceanvende-re og serviceudbydere i webservicens levetid. Webservices skal kunne

Side 9 af 54

realiseres af serviceudbydere ved brug af eksisterende og velbeskrevne metoder samt udbredte værktøjer og rammeværk.

F2. Design af webservices skal tage udgangspunkt i serviceanvenderens be-hov. Det vil sige, at webservices udstilling af data og funktionalitet er in-tuitiv og enkel at anvende for en serviceanvender.

F3. Ændringer i webservices skal udformes således, at det er så omkostnings-effektivt som muligt for serviceanvendere. Ændring af udstillede webservices medfører nødvendige tilpasninger hos serviceanvendere. Ændringer hos serviceanvendere medfører ekstra om-kostninger og kan give stærke bindinger i it-landskabet, ved at en service-udbyder ikke kan ændre en webservice før væsentlige serviceanvendere, eller i værste tilfælde alle serviceanvendere, er klar til ændringen. Hvis an-tallet af serviceanvendere for den pågældende webservice er højt, udgør omkostninger til serviceanvenderes it-løsninger typisk størstedelen af den samlede omkostning ved en ændring af webservicen. Design af webser-vices skal derfor have som mål at minimere konsekvenser for servicean-vendere ved ændringer i en webservice. Det vil være totaløkonomisk for-delagtigt at mindske bindingerne mellem serviceudbyder og servicean-vender, idet bindingerne sænker forandringsevnen i it-landskabet. Dette kan ske ved, at services i høj grad er bagudkompatible, og hver operation i en webservice er fokuseret på netop én forretningsmæssig handling.

F4. Webservices skal have en entydig mekanisme til ansvarsoverdragelse mel-lem myndigheder, således at der altid er klarhed over, hvilken myndighed der har ansvaret for en given myndighedsopgave. Ansvarsoverdragelse kan fx være frigørende virkning for en myndighed ved aflevering af med-delelser til Digital Post.

F5. Webservices skal kunne understøtte forandringer i serviceanvenderes forretningskrav ved hurtigt at kunne understøtte ændringer i data og funktionalitet samt hurtigt at kunne skalere til ændret forbrug heraf.

Tema 2: Forretningsbehov vedrørende data og funktionalitet

Temaet fokuserer på behovene for, at udstilling af data via webservices sker på

en måde, som sikrer mest mulig interoperabilitet.

F6. REST webservices skal udstille forretningsobjekter som ressourcer på en ensartet måde for at sikre interoperabilitet, jf. afsnit 2.1.

F7. Udstilling af webservices skal omfatte dokumentation af de pågældende webservices, herunder dokumentation af regler for syntaks og semantik samt beskrivelse af snitfladen. Dokumentationen skal være tilgængelig både for personer og it-systemer.

F8. REST webservices skal anvende relevante eksisterende og kommende fællesoffentlige datastandarder og profiler for REST ved udvikling af nye versioner af en REST webservice.

F9. Webservices skal udstille data i bredt anvendte dataformater.

Side 10 af 54

F10. Webservices skal tage højde for, at data kan have forskellige grader af fortrolighed, hvilket stiller forskellige krav1 til egenskaberne ved en web-service. Fx kan en webservice udstille personoplysninger.

Tema 3: Forretningsbehov vedrørende stabil og sikker driftsafvikling

Temaet omhandler behovene for, at webservices kan indgå i et fællesoffentligt it-

landskab på en forvaltningsmæssig sikker og effektiv måde.

F11. Serviceudbydere skal kunne dokumentere anvendelsen af data og funkti-onalitet i webservices, herunder webservicens håndterinng af svartider og fejlsituationer.

F12. Webservices skal kunne overvåges, og transaktioner skal kunne spores på tværs af webservices. Webservices skal udstille tilstrækkelige data til at kunne indgå i orkestrering, herunder indeholde dubletkontrol og ensartet struktur af fejlbeskeder.

F13. Webservices skal kunne udstille adgang til data og funktionalitet af for-trolig eller følsom karakter. Når serviceudbyderen anvender (f.eks. dan-ske udgaver af) udbredte, gældende sikkerhedsstandarder i stedet for at definere egne sikkerhedsmodeller, vil kravene til databeskyttelse med hø-jere sandsynlighed være opfyldt.

1 For eksempel er der forskel på krav til webservices, der udstiller offentligt tilgængelige data, og webservices der udstiller personoplysninger til udveksling mellem myndigheder.

Side 11 af 54

3. Generelle retningslinjer for webservices

Dette afsnit indeholder retningslinjer, der understøtter forretningsbehovene be-

skrevet i afsnit 2 og er generelt anvendelige ved implementering af webservices

til it-løsninger i den offentlige sektor, herunder fx REST over HTTP og SOAP.

Retningslinjer, der er specifikke for REST webservices, findes i afsnit 4.

3.1 Fokus på serviceanvendere

En webservice skal være så enkel at anvende som muligt. En webservice er enkel,

når dens operationer udstiller en afgrænset mængde data og funktionalitet på en

entydig måde for en bestemt serviceanvendelse. Dette medfører et større antal

operationer og webservices, som er dedikeret til et bestemt forretningmæssigt

formål. Ved ændringer i forretningsbehov eller ændret lovgivning er det kun en

afgrænset mængde af webservices og/eller operationer, som påvirkes, og dermed

påvirkes så få serviceanvendere som muligt. Et for stort antal webservices inden

for et givet datadomæne vil til gengæld give mere kompleksitet for serviceanven-

dere i orkestrering og viden om sammenhænge mellem services.

En webservice, som udstiller generiske operationer2, kan anvendes af mange

serviceanvendere med forskellige behov. En generisk webservice får derfor man-

ge serviceanvendere, der tilgår snitfladen, men kun anvender en delmængde af

det udstillede data og funktionalitet. En ændring af en generisk webservice kan

således medføre ændringer for alle serviceanvendere, selvom ændringen ikke

omfatter delmængden af data eller funktionalitet, som anvendes af serviceanven-

dere. Det giver bindinger i it-miljøet. Serviceudbyderen har dermed reducerede

muligheder for at ændre generiske webservices uden meromkostninger, risici og

hensynstagen til serviceanvenderes tidsplaner.

Navn: R01. Udstil minimal funktionalitet og data i den en-kelte webservice

Retningslinje Webservices skal designes således, at én webservice kun udstiller tilstrækkelig data eller funktionalitet for at give for-retningsmæssig mening for en bestemt serviceanvendelse.

Rationale En ændring til data og funktionalitet skal som udgangs-punkt kun medføre ændringer i den webservice, der udstiller

2 Et eksempel på en generisk webservice er en webservice, der tillader generel søgning i en mændge udstille-de forretningsobjekter, hvis indre repræsentation (attributter og relationer) direkte gøres tilgængelig for serviceanvendere.

Side 12 af 54

funktionaliteten. På denne måde minimeres behovet for ændringer i etablerede serviceanvenderes klienter. Service-anvenderes klienter skal kun ændres, hvis ændringen påvir-ker deres serviceanvendelse.

Understøttede forretningsbehov

Retningslinjen understøtter forretningsbehov F2 og F3, idet den medfører, at serviceanvendere samlet set påvirkes mindre.

Implikation En webservice løser ideelt set kun én opgave3, hvilket har den konsekvens, at genbrugeligheden af den enkelte web-service bliver reduceret. Til gengæld vil det samlede økosy-stem være bedre i stand til at håndtere ændringer, da det kun vil være serviceanvendere, som har behov for en æn-dring, som påvirkes. Et eksempel er en søgefunktionalitet, som udstilles til mobi-le klienter og rige klienter. Her vil en anvendelse af et back-end to frontend arkitetkurmønster kunne udmøntes i to webservices, en til mobile klienter og en til rige klienter. Ændringer til søgning i den rige klient vil ikke påvirke mobi-le klienter, da webservicen ikke vil ændres.Eksempelvist kan ” Lokalestyrelsen”, jf. appendiks A, udstille en generisk ”Ret” funktion for forretningsobjektet ”mødelokale”, som indeholder et forretningsobjekt, som består af et mødeloka-le og tilhørende bookinger. Funktionen ”Ret mødelokale” skal således understøtte redigering af mødelokalets attribut-ter, men også tilhørende bookinger. Det medfører, at samt-lige serviceanvendere skal anvende ”Ret mødelokale”, selv-om serviceanvendere har forskellige serviceanvendelser, hvor én kun retter mødelokalets data, og en anden kun op-retter bookinger. Et andet eksempel kunne være ved tilføjelse af et nyt obliga-torisk attribut på mødelokale, så vil det være en breaking change for alle serviceanvendere. En mere serviceanvenderrettet tilgang kunne fx være at anvende en service eller operation per serviceanvendelse, fx ”opret booking”, ”opdater mødelokale attributter”. I dette eksempel vil en tilføjelse af et nyt obligatorisk attribut på mødelokalet ikke påvirke serviceanvendere, som kun an-vender funktionen ”opret booking”.

3 Svarende til Single Responsibility princippet fra SOLID (https://en.wikipedia.org/wiki/SOLID_(object-oriented_design) ).

https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)

https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)

Side 13 af 54

Navn: R02. Separér webservices fra konkret implemente-ring

Retningslinje Webservices skal designes, så de afkobler implementeringen af interne og eksterne forretningsobjekter fra den snitflade, der udstilles imod serviceanvendere.

Rationale Ved at anvende en facade, der afskærmer serviceanvenderen fra den konkrete implementering af data og funktionalitet i udbyderens interne miljø, vil serviceudbyderen opnå større friheder i implementeringen af webservicen.


Retningslinjen er affødt af forretningsbehov F3 ved at af-skærme serviceanvenderen fra udbyderens interne, flygtige og evt. irrelevante anvendelse af data og funktionalitet

Implikation Ved servicedesign bør det afdækkes, netop hvilke dele af et forretningsobjekt, der er behov for at gøre tilgængelige for anvendere. Webservicens design bør give disse dele en re-præsentation, der ikke fastholder serviceudbyderen i den samme konkrete implementering af webservicen i hele ser-vicens levetid.

Navn: R03. Separér webservices fra eksterne afhængigheder

Retningslinje Webservices skal designes, så snitfladen udstiller egne data-sæt og ikke har eksterne afhængigheder til andre domæners objekter.

Rationale Når webservicen udstiller en facade foran den bagvedlig-gende forretning, får serviceanvenderen kun det nødvendige data, for at reducere kompleksitet og gardere mod konse-kvenser af ændringer fra bagvedliggende syste-mer.Forretningsmæssige webservices, der udstiller data, kan være en aggregering af data fra andre webservices. Webser-vicen definerer med andre ord sit eget datasæt (egen facade) eller gennemstiller data direkte. Såfremt data udstilles af webservicen som en facade, så vil ændringer til bagvedlig-gende webservices ikke påvirke serviceanvendere, medmin-dre facaden ændres.


Retningslinjen er affødt af forretningsbehov F3 ved at af-skærme serviceanvenderen fra fremmede forretningsobjek-ter.

Implikation Ved servicedesign skal det afdækkes, hvilke dele af data der er behov for at gøre tilgængelige for anvendere. Samtidigt vil anvendelsen af facader dog øge omkostningen ved æn-dringer i bagvedliggende webservices, da facaden skal opda-teres.

Side 14 af 54

3.2 Ansvarsfordeling ved kald til webservices

Ved integrationer mellem forskellige myndigheders it-systemer er det centralt, at

ansvaret for gennemførsel og fejlhåndtering ved en transaktion er tydeligt place-

ret. Dette gør sig særligt gældende ved kald til webservices, hvor funktionaliteten

medfører overdragelse af ansvar mellem myndigheder. Fx kan det være i forbin-

delse med overførsel af en administrativ opgave i forbindelse med en partens

flytning af bopælsadresse.

Ændring af data skal gennemføres entydigt. Serviceudbyderen skal derfor hånd-

tere, at opdatering af hele ressourcer er idempotente, mens delvise opdateringer

ikke er idempotente. Dette er uddybet i Bilag 2 ”Fejlstruktur og fejlkoder for

REST Webservices” og Bilag 4 ”Specifikation for brug af HTTP til REST”.

Navn: R04. Understøt gentagne forsøg på kald fra service-anvenderen

Retningslinje En webservice skal entydigt kunne håndtere gentagne for-søg fra serviceanvenderen.

Rationale En klar ansvarsplacering i forbindelse med gennemførsel af kald er nødvendig for, at informationer og evt. ansvar for behandling overdrages korrekt. Det er kun serviceanvende-ren, der kan afgøre, om svaret på et kald er modtaget.


Retningslinjen er affødt af forretningsbehov F4.

Implikation Det er serviceanvenderen, der er ansvarlig for at gennemfø-re et kald, herunder at genforsøge kaldet, indtil et svar (en fejl eller en kvittering) modtages fra webservicen. Hvis ansvarsoverdragelsen kræver, at et bagvedliggende forretningssystem skal opdateres asynkront, så gælder det, at REST webservices skal følge mønsteret for asynkrone kald, som beskrevet i Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices”. Webservices kræver, at en serviceanvender medsender en transaktionsidentifikator ved alle kald, jf. retningslinje R14, derfor kan transaktionsidentifikatoren anvendes af service-udstiller til at detektere gentagne forsøg, og håndtere genta-gelsen korrekt.

Navn: R05. Kræv specifikke informationer ved ansvarsover-dragelse ved kald til webservices

Retningslinje Webservices, der understøtter overdragelse af myndigheds-ansvar, skal kræve, at specifikke overdragelsesinformationer inkluderes i kaldet og skal eksplicit returnere en kvittering for, at overdragelsen er accepteret.

Side 15 af 54

Rationale Det skal være uomtvisteligt, hvornår en offentlig institution eller en organisation (som serviceanvender) har overdraget et ansvar til en anden myndighed eller en organisation (som serviceudbyder). For at sikre dette skal webservicen kræve, at serviceanvenderen har inkluderet specifikke informatio-ner om overdragelse af ansvar i kaldet. Den valgte kommu-nikationsprotokols (fx HTTP) tekniske kvitteringer kan ikke nødvendigvis erstatte forretningsmæssige kvitteringer for ansvarsoverdragelse. Fx kan en snitflade måske ikke syn-kront opdatere de bagvedliggende forretningssystemer. Dermed kan serviceudbyder ikke give en forretningsmæssig kvittering, før alle bagvedliggende systemer er opdateret korrekt.



Implikation Serviceudbyderen skal designe webservicen således, at ek-splicitte overdragelsesinformationer skal være til stede i et korrekt kald til webservicen. Disse informationer kan fx omfatte:

Identifikation af den ansvarsafgivende organisati-on/myndighed.

Identifikation af den ansvarsmodtagende organisa-tion/myndighed.

En unik identifikator af denne ansvarsoverdragelse.

En identifikation af hvilket ansvar, der overdrages, f.eks. ved reference til en aftalt klassifikation, em-nesystematik eller lovgrundlag.

Serviceudbyderen skal realisere webservicen, så den returne-rer et kvitteringssvar, der indikerer, at ansvaret er overdra-get. Såfremt en REST webservice opdaterer det bagvedligggen-de forretningsystem asynkront for at kunne overdrage an-svar, så skal forretningskvitteringen følge mønsteret beskre-vet i Bilag 2 ”Fejlstruktur og fejlkoder for REST Webser-vices”.

3.3 Servicedokumentation

Serviceudbydere skal dokumentere alle udstillede webservices. Dokumentationen

skal målrettes serviceanvenderens behov for information, både forretningsmæs-

sigt og teknisk. God dokumentation målrettet serviceanvendere kan reducere

omkostningerne, når udstillede webservices skal anvendes, da det bliver lettere

for serviceanvenderen at vælge og bruge udstillede webservices korrekt.

Side 16 af 54

Serviceanvenderes behov består af forretningsforståelse og teknisk forståelse af

data, der udveksles, samt koblingen mellem forretningsmodeller og konkrete

datarepræsentationer. Forretningsmæssige krav om data og funktionalitet af den

udstillede webservice er en central del af dokumentationen, der skal give service-

anvenderen tilstrækkelig viden.

Navn: R06. Dokumentér udstillede webservices i overens-stemmelse med den fællesoffentlige dokumen-tationsramme for webservices

Retningslinje Dokumentationen for webservices skal følge den fællesof-fentlige dokumentationsramme, der udgøres af Bilag 1 ”Dokumentation for REST Webservices”.

Rationale God dokumentation er opdelt og opmærket på en måde, der gør, at dokumentationens enkeltdele målrettes de for-skellige roller hos serviceanvenderen (f.eks. forretningsan-svarlig eller it-arkitekt). Det er en nødvendig forudsætning, at den udstillede dokumentation altid er ajourført, så doku-mentationen svarer til den udstillede webservice. Alle webservices skal være dokumenterede i overensstem-melse med den fællesoffentlige dokumentationsramme, og dokumentationen skal være let tilgængelig, ajourført og sva-re til de udstillede webservices. Dokumentationen muliggør, at serviceanvendere forstår, hvordan udstillede webservices anvendes uden at skulle konsultere eller kontakte serviceudbyderen. Ved fx at syn-liggøre semantik og syntaks sikres synlighed og ensartethed, så webservicedata og funktionalitet har samme betydning for både serviceudbyder og serviceanvender. Serviceudbyderen mindsker ressourceforbruget i sin sup-port, når let tilgængelig dokumentation medfører, at ser-viceanvenderen kan finde de relevante dele af dokumentati-onen.



Implikation Krav til dokumentationen fremgår af den fællesoffentlige dokumentationsramme for webservices, som er beskrevet i Bilag 1 ”Dokumentation for REST Webservices”. Dokumentation af webservices skal overholde de krav, som er angivet i Bilag 1 afsnit 2 og skal stille tilsvarende doku-mentation til rådighed, jf. Bilag 1 afsnit 3. For REST webservices gælder det, at serviceudstiller skal anvende OpenAPI med SmartAPI udvidelser. Ved alle æn-dringer til webservicen skal dokumentationen opdateres, senest når ændringen idriftsættes, således at en webservice altid er udstillet med opdateret dokumentation.

Side 17 af 54

Navn: R07. Opmærk webservices i henhold til fællesoffentlige emnesystematikker

Retningslinje Serviceudbyderen skal opmærke udstillede webservices i henhold til fællesoffentlige emnesystematikker.

Rationale Serviceudbyderen skal opmærke webservices i henhold til emnesystematik, således at serviceanvendere tydeligt kan se, hvilken offentlig forvaltning, forvaltningsproces eller anden proces hos serviceudbyderen, webservicen er udstillet i rela-tion til. Som en del af den forretningsrelaterede del af do-kumentation for webservices skal serviceanvenderen bibrin-ges viden om, hvilken offentlig forvaltning, forvaltnings-processer eller andre processer, webservicen er en del af hos serviceudbyderen.


Retningslinjen er affødt af forretningsbehov F2

Implikation Dokumentationen af den enkelte webservice skal inkludere opmærkning i henhold til fællesoffentlige emnesystematik-ker, dvs. enten KLE, FORM eller anden relevant, anerkendt fællesoffentlig emnesystematik. Opmærkningen beskrives for den enkelte webservice. Hvis en webservice indgår i flere forvaltningsprocesser eller for-valtningsemner, skal alle emnerne angives i dokumentatio-nen. Opmærkningen for REST webservices skal foretages som angivet i Bilag 1 ”Dokumentation for REST Webservices” .

Navn: R08. Opmærk webservices med følsomhed eller for-trolighed af data

Retningslinje Serviceudbyderen skal i dokumentationen opmærke udstil-lede webservices med en angivelse af følsom-hed/fortrolighed af data, der skal angives enten ved kald eller returneres ved svar.

Rationale Serviceudbyderen angiver følsomhed for de data, der over-føres ved brug af webservicen (dvs. både kald og svar) i dokumentationen. Som en del af den sikkerhedsrelevante del af dokumentation for webservices skal serviceudbyderen angive følsomhed eller fortroligheden, så det fremstår tyde-ligt overfor serviceanvenderen, hvordan data til og fra web-servicen skal behandles.



Implikation Opmærkningen angives ikke i selve kaldet eller svaret, men som en del af webservicens dokumentation. Dokumentati-onen af den enkelte webservice skal inkludere opmærkning i henhold til klassificering af følsomhed og fortrolighed i den fællesoffentlige dokumentationsramme for webservices.

Side 18 af 54

Opmærkningen påføres den enkelte webservice i form af angivelse af fortroligheds- eller følsomhedsniveauer fra en klassifikation af niveauer i den fællesoffentlige dokumenta-tionsramme. En REST webservice skal opmærke følsomhed og fortro-lighed i OpenAPI, jf. Bilag 1 ”Dokumentation for REST Webservices” afsnit 3.2.9. Hvis en webservice har data med flere niveauer, angives det højeste niveau af følsomhed eller fortrolighed, jf. klassifika-tion af niveauer i den fællesoffentlige dokumentationsram-me.

Serviceanvenderen har behov for at kende til de servicespecifikke fejl, en web-

service kan returnere som svar på kald til webservicen. Servicespecifikke fejl er

fejl, der opstår i udveksling mellem service og serviceanvender. Fx hvis service-

anvenderen har angivet en værdi, der ikke tillades af webservicen. Denne fejl er

servicespecifik, da den (først) opstod i forbindelse med webservicens behandling

af kaldet, efter kaldet var transporteret til webservicen.

Navn: R09. Dokumentér servicespecifikke fejlkoder for webservices

Retningslinje Alle servicespecifikke fejl, der kan returneres fra en webser-vice, skal dokumenteres, og dokumentationen skal indgå i webservicens dokumentation og gøres tilgængelig for ser-viceanvendere.

Rationale Serviceanvendere skal kunne forstå, hvorfor kald til en ud-stillet webservice ikke kan gennemføres, så serviceanvende-ren eventuelt kan kompensere for problemet. Hvis service-specifikke fejl dokumenteres, får serviceanvenderen mulig-hed for selv at løse problemerne i stedet for at skulle bebyr-de serviceudbyderen med bistand til at løse problemet.



Implikation Dokumentationen for webservices skal inkludere en over-sigt over alle servicespecifikke fejl, samt dokumentation af hver enkelt servicespecifik fejl. Dokumentationen af den enkelte servicespecifikke fejl bør angive, hvilken fejlkode (en værdi) fejlen er identificeret ved, en fejlbeskrivelse og årsag. Dokumentationen af servicespecifikke fejl er en del af web-servicens dokumentation og skal udstilles til serviceanven-dere. Fejlhåndtering for serviceudbyder omfatter ikke fejl i infrastrukturen mellem serviceanvender og webservice.

Side 19 af 54

Fejlbeskrivelser og statuskoder for REST webservices skal overholde retningslinjerne for servicefejlmeddelelser, jf. Bilag 4 ”Specifikation for brug af HTTP til REST”og afsnit 3.7.Fejlstrukturer for alle webservices skal overholde fejl-strukturen beskrevet i bilag 4.

Serviceudbydere vil øge interoperabiliteten ved at tydeliggøre ændringer til web-

services, så serviceanvendere kan afgøre, om ændringens effekt fordrer konse-

kvensændringer hos dem selv.

Navn: R10. Dokumentér drift af forskellige versioner af webservices

Retningslinje Serviceudbyderen skal dokumentere vilkårene i forbindelse med samtidig driftsafvikling af versioner af den samme webservice.

Rationale Serviceanvendere kan få fordel af at være tydeligt informe-rede om de vilkår, der gælder, når serviceudbyderen udstiller forskellige versioner af en webservice. Serviceanvenderen skal vide, hvor lang tid denne har til at tilpasse sig en ny version af en webservice, hvis der foretages en ikke-kompatibel ændring af denne, jf. retningslinje R11 om ver-sionering).



Implikation Serviceudbyderen skal fastlægge og dokumentere sin relea-se- og versioneringsstrategi for den enkelte webservice, jf. retningslinje R11, og publicere denne sammen med doku-mentationen for udstillede webservices. Serviceudbydere skal dokumentere deres strategi for, i hvilket omfang for-skellige versioner af en udstillet webservice driftsafvikles samtidigt. Serviceanvendere får dermed en forståelse for, hvor hurtigt de skal tilpasse sig ved ændringer til webser-vice. Det bør fremgå af dokumentationen:

Hvordan webservices versioneres i henhold til R11.

Hvor længe gensidigt inkompatible webservices ud-stilles i flere udgaver, samt antallet heraf.

Om, og i givet fald hvor længe i forvejen, service-udbyderen adviserer serviceanvendere om ændrin-ger.

Hvordan serviceanvendere eventuelt kan identficere sig over for serviceudbyder.

Hvordan serviceudbyderen udstiller en oversigt over konkrete datoer for publicering af nye webservices

Side 20 af 54

samt ændringer til og nedlæggelse af eksisterende webservices.

3.4 Serviceversionering

Det er centralt for serviceanvendere, at de er i stand til at afgøre, om en ændring

til en webservice kræver korresponderende ændringer hos serviceanvenderen.

Konsekvenserne af sådanne ændringer skal generelt minimeres.

Når ændringer er nødvendige, skal webservicens version tydeligt indikere over

for serviceanvenderen, om webservicen er kompatibel med den tidligere udgave.

Ved kompatibilitet forstås i denne forbindelse, at én version af en webservice er

kompatibel med en tidligere version, hvis der ingen ændringer kræves hos ser-

viceanvenderen.

Versionering af udstillede webservices er via mekanismen ”semantisk versione-

ring”4 et middel til at gøre det klart, tydeligt og entydigt over for serviceanvende-

re, om der er fortaget ændringer, der kræver handling fra serviceanvenderens

side. Ifølge reglerne for semantisk versionering anvendes et versionsnummer

med tre dele: major version, minor version og patch version. Reglerne for versi-

onsnumre er således:

To versioner af en webservice med forskellige major versioner (f.eks. 1.1 og 2.0) er ikke kompatible. En serviceanvender, der anvender version 1.1 af webservicen, vil skulle foretage ændringer for at kunne anvende versi-on 2.0 af webservicen.

Når to versioner af en webservice har samme major version men forskel-lige minor versioner (f.eks. 1.1 og 1.2), er version 1.2 af webservicen kompatibel med version 1.1. Serviceanvenderen skal derfor ikke foretage sig noget for at skifte fra version 1.1 til 1.2, men der er formodentlig mu-lighed for at anvende mere funktionaltiet i den nye version.

Hvis to versioner af en webservice har samme major og minor version men for-

skellig patch version, skal serviceanvenderen ikke foretage sig noget for at skifte

mellem de to versioner.I denne forbindelse er det væsentligt, hvilken ressource

der versioneres. Serviceudbyderen kan dog ikke ændre den faste del uden at æn-

dre en ressources URI, som er den unikke sti til en given ændring, fx ændring af

4 Semantisk versionering er en oversættelse af ”Semantic Versioning”, der er beskrevet her: http://semver.org

http://semver.org/

Side 21 af 54

serverens DNS navn i en HTTP URI for en REST ressource – dette opfattes

derfor som en ikke-kompatibel ændring.

Navn: R11. Anvend semantisk versionering af webservices

Retningslinje Webservices skal anvende semantisk versionering til at tyde-liggøre kompatibilitet og overholde versioneringsreglerne.

Rationale Serviceanvendere skal gøres tydeligt opmærksomme på, hvornår ændringer til en udstillet webservice er kompatibel med eksisterende serviceanvendelser, og hvornår dette ikke er tilfældet. Semantisk versionering indeholder flere kom-ponenter i et versionsnummer, der gør dette klart: ændrin-ger i ”major” komponenten i servicens versionsnummer betyder brud på kompatibilitet med eksisterende servicean-vendelser.


Retningslinjen er affødt af forretningsbehov F2 og F3.

Implikation Webservices skal garantere kompatibilitet mellem versioner af en webservice ifølge reglerne for semantisk versionering. Webservices kan eventuelt understøtte, at serviceanvende-ren kan specificere den ønskede version af webservicen i forbindelse med et kald. En konsekvens af denne versionering er, at følgende æn-dringer generelt medfører en ny major version:

En valgfri kaldsparameter bliver obligatorisk.

Tilføjelse af en ny obligatorisk parameter ved kald.

Fjernelse af værdier i svar.

Semantiske ændringer af data i kald eller svar Listen er ikke udtømmende. Andre ændringer, som fx ændring af sikkerhedsmodel og sletning af udstillede attributter eller relationer, er normalt en ikke-kompatibel ændring. Andre ikke-kompatible æn-dringer, der kræver nyt versionsnummer, er f.eks. introduk-tion af nye obligatoriske parametre eller begrænsning i mængden af mulige parametre.

Navn: R12. Viderefør gamle versioner, når en webservice ændres

Retningslinje Serviceudbyderen skal videreføre versioner i en tilstrækkelig overgangsperiode.

Rationale Når der sker ikke-kompatible ændringer til udstillede web-services bør både den nye version og den hidtidige version være tilgængelige samtidigt i en overgangsperiode for at lette overgangen og mindske tidspresset for serviceanvenderne.

Side 22 af 54

Eksisterende serviceanvendere vil kun undtagelsesvist skulle tilpasse sig til brug af en ændret webservice. Serviceudbyde-ren må derfor antage, at serviceanvendere har behov for en overgangsperiode, hvor både gammel og ny udgave af web-servicen udstilles samtidigt.



Implikation Hvis ændringen udgør en breaking change, skal serviceud-byderen udstille både ny og gammel version af webservicen i en overgangsperiode. Serviceudbyderen skal dokumentere dette, jf. retningslinje R10.

3.5 Servicelogning

Logning og juridiske krav til logning er ikke færdig analyseret i version 0.9, dette afsnit er

derfor ikke endeligt.

I forbindelse med integration mellem it-løsninger er det nødvendigt, på forlan-

gende, at kunne redegøre for afviklingen af et kald og svar herpå. Typiske fejlsi-

tuationer kunne fx være, at en given handling fra en bruger har forårsaget en fejl,

som er opstået i kæde af servicekald.

Navn: R13. Log alle kald til webservices

Retningslinje Alle væsentlige kald til og svar fra webservices skal logges af serviceudbyderen.

Rationale Det skal sikres, at alle væsentlige kald til en webservice log-ges. Væsentlige kald omfatter bl.a. kald, der indeholder eller kan indeholde følsomme eller fortrolige data i kaldet eller svaret på kaldet. Kaldet og svaret skal kunne spores for at bl.a. krav til logning i forbindelse med behanding og slet-ning af persondata kan opfyldes.


Retningslinjen er affødt af forretningsbehov F2, F12 og F11.

Implikation Serviceudbyder skal logge alle kald til en given webservice, hvor følsomme eller fortrolige informationer behandles i henhold til relevant lovgivning. Serviceudbyder skal desu-den overveje, om data af ikke-følsom eller ikke-fortrolig natur skal logges. Det er traditionelt set serviceudbyderen, der foretager logning af modtagne kald samt de svar, som returneres til serviceanvenderen. Svar kan imidlertid gå tabt på vej tilbage til serviceanvenderen. Derfor er det nødven-digt, at både serviceanvender og serviceudbyder foretager logning. Serviceudbyderen skal dokumentere, hvilke kald en given webservice logger.

Side 23 af 54

Webservicen skal desuden foretage logning af alle eksterne kald, der foretages som konsekvens af det modtagne kald, hvor fortrolige eller følsomme data er involverede.

For at sikre at logningen hos serviceanvender og serviceudbyder kan sammen-

holdes, skal det enkelte kald være unikt identificeret. En sådan identificering har

form af en unik transaktionsidentifikator.

Navn: R14. Anvend transaktionsidentifikatorer ved kald og svar

Retningslinje Webservices skal kræve en transaktionsidentifikator ved kald og skal returnere transaktionsidentifikator ved svar. Serviceudbyder sender transaktionsidentifikator med videre, hvis forespørgslen giver anledning til kald videre til andre webservices

Rationale Det skal være muligt for serviceanvendere og serviceudby-dere at spore sammenhængen i servicekald på tværs.



Implikation Serviceudbyderen skal kræve, at serviceanvenderen med-sender en globalt/universelt unik transaktionsidentifikator for hvert kald til en udstillet webservice. Transaktionsidentifikatoren kan f.eks. være et UUID, jf. ietf RFC 4122. Webservicens svar skal inkludere transaktionsidentifikatoren fra kaldet. Webservices sender transkationsidentifikatoren med videre, hvis forespørgslen giver anledning til kald videre til andre webservices.

Navn: R15. Anvend requestID ved kald og svar

Retningslinje Webservices skal logge et unikt requestID ved hvert kald, og ved gensendelse af et svar skal samme RequestID an-vendes.

Rationale Entydighed af det enkelte kald giver mulighed for sporing på tværs af services. Det skal være muligt for serviceanvendere og serviceudby-dere at spore individuelle kald. Ved at inkludere en regues-tID i kald og svar, vil det være muligt for både servicean-vender og serviceudbyder at identificere et bestemt kald.

Understøttede Retningslinjen er affødt af forretningsbehov F1, F12 og

Side 24 af 54

forretningsbehov F11.

Implikation Serviceudbyderen skal medsende en unik requestID for hvert kald til en udstillet webservice. RequestID kan f.eks. være et universelt unikt id, jf. internet RFC 4122.

3.6 Servicetilgængelighed

Monitorering af tilgængelighed til anvendte webservices kan bistå håndtering af

løsning eller omgåelse af fejl i it-landskabet. Serviceudbyderen skal derfor udstille

informationer om webservicens tilgængelighed til serviceanvendere. Servicean-

vendere kan anvende informationen til at afgøre, om en udstillet webservice er

tilgængelig på et givet tidspunkt.

Navn: R16. Understøt monitorering af udstillede webser-vices

Retningslinje Udstillede webservices skal understøtte, at serviceanvende-ren kan monitorere webservicens tilgængelighed.

Rationale Serviceanvendere har ved unormale driftssituationer behov for at afgøre, om anvendte webservices er tilgængelige eller ikke, og om eventuelle driftsforstyrrelser er placeret hos serviceanvenderen eller hos serviceudbyderen. Udstilling af dedikeret monitoreringsfunktionalitet har typisk større ro-busthed end de webservices, der anvendes til forretnings-processerne.



Implikation Udstillede webservices skal udstille en snitflade, som viser, om en webservice er tilgængelig eller ikke. Monitoreringen kan enten være inkluderet som en dedikeret (del)funktionalitet af en udstillet webservice eller være ud-stillet som en sideordnet webservice. Udstillede webservices kan eventuelt udstille specifik funk-tionalitet til visning af tilgængeligheden af webservicens og at ressourcer, som webservicen er afhængig af, er tilgængeli-ge. En sådan funktionalitet har typisk ingen parametre og kræver ingen sikkerhedsmæssige rettigheder hos servicean-venderen. Alternativt kan monitorering understøttes ved at dokumentere en særlig måde at anvende en udstillet web-service på. Dette kunne fx være et fremsøgningskald, der aldrig returnerer data, men svarer med 0 fundne forret-ningsobjekter, og hvor brugen heraf til monitorering er do-kumenteret af serviceudbyderen. Det er centralt, at monitoreringen ikke foretager opdaterin-

Side 25 af 54

ger i data. Logning hos serviceudbyderen er i denne forbin-delse ikke at betragte som en opdatering af data. Man kan fx oprette en booking af et lokale som en test af tilgængelighed af en lokaleservice, jf. appendiks A.

3.7 Servicefejlmeddelelser

Når fejl opstår i forbindelse med behandling af et kald til en udstillet webservice,

er det vigtigt for efterfølgende analyse af fejlen, at tilstrækkelige informationer

om fejlen er leveret til serviceanvenderen. Serviceanvenderen skal selv kunne

analysere fejlens detaljer og ved hjælp af den modtagne dokumentation afgøre,

hvordan fejlen efterfølgende skal håndteres. Dette stiller væsentlige krav til de

informationer, der returneres af en udstillet webservice i forbindelse med fejl.

Fejlbeskrivelser er uddybet i Bilag 2 ”Fejlstruktur og fejlkoder for REST Web-

services”.

Navn: R17. Returnér servicespecifikke fejl som standardise-rede fejlmeddelelser

Retningslinje Webservices skal returnere servicespecifikke fejl som stan-dardiserede fejlmeddelelser til serviceanvenderen med do-kumenterede fejlkoder som beskrevet i Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices”.

Rationale Dokumentationen af fejlmeddelelser skal angive over for serviceanvenderen, om kaldet er idempotent. Serviceudby-deren bør dog kun angive, at et gentaget kald er en fejl, når serviceudbyderen med sikkerhed ved, at gentagelse vil resul-tere i samme fejl. For det første er det vigtigt, at alle fejl forsynes med en do-kumenteret fejlkode (en entydig værdi, f.eks. et tal) og et fejlnavn (en overskrift), så serviceanvenderen kan finde fejlen i servicens dokumentation. For det andet er det vigtigt, at alle fejlmeddelelser indehol-der identifikation af, hvor fejlen er opstået, hvilket både kan være hos serviceudbyderen eller hos et system, der kaldes af serviceudbyderen. Meget store fejlmeddelelser skal dog undgås grundet bånd-breddeforbrug. Desuden må fejlmeddelelsen ikke indehol-de data, som påvirker sikkerhedskrav og krav om informa-tioners følsomhed og fortrolighed. Webservices skal derfor anvende den fællesoffentlige struk-tur for fejlmeddelelser for webservices. Strukturen beskrives i Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices”. REST webservices skal endvidere anvende de statuskoder

Side 26 af 54

og headere, som er beskrevet i bilag 2. Serviceanvendere er afhængige af præcise og især fyldestgørende fejlmeddelelser, således at serviceanvenderen gøres i stand til at håndtere fejlen enten manuelt eller automatisk. En utilstrækkelig fejlmeddelelse medfører, at serviceanvenderen ikke vil kun-ne udføre fejlhåndtering. Data eller opdateringer af data kan dermed gå tabt.


Retningslinjen er affødt af forretningsbehov F2, F6 og F12. Retningslinjen præciserer OIO serviceprincippet ”Services returnerer sigende fejlmeddelelser”, jf. [OIOSVC].

Implikation Fejlmeddelelser vedrørende servicespecifikke fejl returneres i den fællesoffentlige struktur for fejlmeddelelser, jf. Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices”. Fejlmeddelelser skal anvendes i kontekst af den valgte transportprotokol, der også returnerer fejlkoder. For REST webservices gælder retningslinje R37. Det betyder, at trans-portprotokollens fejlkoder skal bruges korrekt, når service-specifikke fejl returneres i svar.

Side 27 af 54

3.8 Temporale ressourcer

Der kan være behov for at angive forskellige tidsmæssige aspekter af en ressour-

ce – såkaldte temporaler – i en webservice. Dette afsnit indeholder retningslinjer

for ensartet udstilling af temporaler, hvor en serviceudbyder finder dette nød-

vendigt. Dette dokument stiller således ikke krav om udstilling af temporalitet,

men giver retningslinjer for, hvordan temporalitet skal udstilles, når temporalitet

er en del af webservices.

Et eksempel på en temporal kan være et datostempel for, hvornår en ressource

sidst er blevet ændret. Det vil sige, hvornår en given transaktion er gennemført

for en ressource. Dette implementeres typisk som en traditionel logning, hvor

det er muligt at danne historik over transaktioner, som har fundet sted på den

pågældende ressource, se også eksemplet angivet i Appendiks A.

Der er også andre dimensioner af temporaler, hvor man kan angive gyldigheds-

perioder for en ressource. Hermed forstås den periode, som den pågældende

transaktions indhold er gældende for. Fx kan en bevilling gælde for en bestemt

periode. Ofte kan gyldighedsperioden indikere, hvornår datas betydningsindhold

antages at være i overensstemmelse med den registrerede virkelighed

Udstillet data, som indeholder mere end en enkelt temporal dimension, betegnes

som en multi-temporal model. Typisk begrænser dette sig i praksis til to tempo-

rale dimensioner og benævnes ’bitemporalitet’. Bitemporale ressourcer er karak-

teriseret ved, at det er muligt at gennemgå en registreringshistorik for at se,

hvornår hvilke informationer om den pågældende ressource blev registreret. Det

er samtidig muligt at se gyldigheden (kaldes også virkning i grunddata og OIO)

for ressourcen (eller dele heraf).

Fx kan et mødelokales størrelse have forskellige værdier over tid, som skifter i

forbindelse med renovering. Et lokale kan således være 12 m2 fra 2000 -2010,

20m2 2010 -2015 og 2015-2017. En administrator retter dog først størrelsen på

det sidste mødelokale (20m2) i 2016. Registreringen foretages således i 2016, men

de 20m2 er gyldige fra 2015, hvor den sidste renovering blev foretaget.

Dette kan anskueliggøres med et eksempel, hvor en ressource opdateres på tre

på hinanden følgende tidspunkter. For ressourcen foretages først en opdatering

for periode 1 [g0;g1] til registreringstidspunktet r0. Efterfølgende opdateres res-

sourcen til at gælde for periode 2 [g1;g2] til registreringstidspunktet r1. Og ende-

ligt opdateres ressourcen til at gælde for periode 3 [g0;g2] til registreringstids-

punktet r2. Figuren nedenfor illustrerer, hvorledes den bitemporale plan for ek-

semplet ser ud.

Side 28 af 54

Figur 1 Illustrativt eksempel på registreringhistorik og gyldighedsperioder med tre registreringer

Bitemporale ressourcer anvendes til at understøtte en lang række særskilte for-

retningsbehov afhængigt af det enkelte domæne:

1. Behov for at kunne registrere gyldighed for en ressource for og/eller bagud i tid.

2. Behov for at kunne fremsøge ressourcens tilstand til et givent gyldigheds-tidspunkt og registreringstidspunkt er ”nu”- også kaldet et Punkt eller et øjebliksbillede.

3. Behov for at kunne fremsøge ressourcens gyldige tilstande over en peri-ode - også kaldet en Linje.

4. Behov for at kunne se registreringsperioden for en gyldighedstidsperiode - også kaldet en Flade.

Side 29 af 54

Figur 2 Søgemuligheder ved bitemporalitet

For at imødekomme disse fire generelle behov opstilles følgende retningslinjer:

Navn: R18. Forretningsregler vedrørende temporaler ind-kapsles og håndhæves på serviceniveau

Retningslinje Webservices, som udstiller temporale data, skal garantere datas integritet i samtlige temporale dimensioner.

Rationale Serviceudbyderen skal sikre, at den udstillede service valide-rer input fra opdaterende servieoperationer, således at res-sourcens integritet bevares gennem hele ressourcens levetid.


Retningslinjen understøtter forretningsbehov F2 og F3, idet den sikrer høj datakvalitet for serviceanvendere.

Side 30 af 54

Implikation En webservice skal designes således, at ressourcens integri-tet bevares. Særligt gælder det at Ressourcer, som indehol-der referencer til andre ressourcer med eget gyldighedsom-råde skal sikre integriteten , især hvis disse ressourcer også udstiller temporale egenskaber. En måde at imødekomme denne udfordring på er at opsplitte snitfladens opdaterende operationer fra de fremsøgende operationer5. Det betyder for et REST-baseret snitflade, at der skal udstilles dedikere-de ressourcer, som opretter og vedligeholder udstillede data.

Som udgangspunkt skal en temporal ressource kunne tilgås så enkelt som over-

hovedet muligt for en serviceanvender. Derfor er der behov for en ensartet, for-

enklet udstilling af temporale ressourcer.

Navn: R19. Webservices med temporale ressourcer returne-rer som et øjebliksbillede

Retningslinje Webservices, som udstiller bitemporale ressourcer, skal returnere det øjebliksbillede for registring og gyldighed, som er gældende for fremsøgningstidspunktet, medmindre andet angives af serviceanvender.

Rationale Selvom det er muligt at angive andre intervaller i et tempo-rale, så er det typiske scenarie – også for temporale ressour-cer - at fremsøge et gældende øjebliksbillede. Derfor bør default (det vil sige, hvis der ikke eksplicit er angivet andre værdier i servicekaldet) være et retursvar med et sådan øje-bliksbillede af den temporale ressource.


Retningslinjen understøtter forretningsbehov F2 og F3, idet den sikrer, at servicesanvendelsen forenkles for servicean-vendere.

Implikation Webservices, som udstiller søgning i temporale data, skal fremfinde det gældende øjebliksbillede på søgetidspunktet. Det medfører, at temporal funktionaltitet skal udstilles i særlige adskilte funktioner rettet mod givne forretningsbe-hov. Webservices kan således kun udstille temporaler for et gi-vent gyldighedstidspunkt og registeringstidpunkt (et punkt), mens returnering af flader og linjer af gyldighed kun kan returneres i dedikerede funktioner.

5 Dette betegnes som ’Command Query Responsibility Segregation’. Se http://udidahan.com/wp-content/uploads/Clarified_CQRS.pdf for en uddybning.

http://udidahan.com/wp-content/uploads/Clarified_CQRS.pdf

http://udidahan.com/wp-content/uploads/Clarified_CQRS.pdf

Side 31 af 54

For at sikre genkendelighed på tværs af services, som udstiller temporale res-

sourcer, er det vigtigt, at gyldighedsperioder og registeringsperioder i søgepara-

metre udtrykkes ensartet.

Navn: R20. Webservices med temporale ressourcer anven-der anerkendte nøgleord i søgeparametre.

Retningslinje Webservices, som udstiller funktionalitet, der indeholder temporale ressourcer, skal anvende søgeparameteren ”Gyl-digTidspunkt”, som angiver tidspunkt for gyldighed som ønskes vist, i det tilfælde at servicen har bitemporalitet. Registreringstidspunkt er altid webservicens tidspunktet for modtagelse af kaldet og skal ikke udstilles som parameter.

Rationale Der anvendes anerkendte nøgleord som temporale søgepa-rametre for at gøre det genkendeligt over for serviceanven-dere, hvorledes en webservice, som udstiller temporale res-sourcer, kan kaldes. Temporalitet øger dog kompleksiteten af webservicen både i parametre og det resulterende data-sæt, og derfor skal funktionalitet som standard kun under-støtte øjebliksbilleder.



Implikation Webservices, som håndterer bitemporale ressourcer, skal designes således, at søgeparametre, som vedrører en res-sources temporaler, anvender anerkendte nøgleord.

Navn: R21. Webservices med temporale ressourcer skal udstille ensartet funktionalitet til revision og Linje

Retningslinje Webservices, som ønsker at udstille flader og linje for tem-porale ressourcer, skal designes således, at funktionaliteten udstilles som en selvstændig ikke-opdaterende ressource. Webservices, som er dedikerede funktioner for Linje og flader, der udstiller temporale ressourcer, skal anvende føl-gende nøgleord som søgeparametre:

”GyldigFra”, der angiver starttidspunkt for gyldig-hed.

”GyldigTil”, der angiver sluttidspunkt for gyldighed.

”RegistreringFra”, der angiver starttidspunkt i et in-terval i en flade.

”RegistreringTil”, der angiver sluttidspunkt i et in-terval i en flade.

Rationale Da bitemporal logik kan være vanskelig at kommunikere og forstå, er det vigtigt, at servicen designes således, at det er

Side 32 af 54

tydeligt, hvornår der fremsøges et øjebliksbillede, linje hhv. flade. Sidsnævnte må ikke forveksles med linje, hvorfor det er vigtigt, at det er tydeligt og entydigt, hvilken temporal dimension, som returnes af servicens fremsøgninger. Et fremsøgning af en flade vil som oftest blive anvendt i væsentligt mindre grad end henholdsvis fremsøgning af et øjebliksbillede og Linje for en given temporal ressource. Dette skal afspejles i designet af webservicen.


Retningslinjen understøtter forretningsbehov F2 og F3, idet den sikrer, at serviceanvendelsen forenkles for servicean-vendere.

Implikation Webservices, som udstiller temporale ressourcer, skal desig-nes således at, såfremt der er behov for udstilling af en fla-de, så udstilles fladen som en særskilt ressource og ikke som et søgeparameter på den temporale ressource. En flade skal i sagens natur være immutabel, hvorfor det ikke er tilladt at understøtte en flade med opdaterende operationer (fx PUT, POST, DELETE i REST).

Navn: R22. Webservices med temporale ressourcer skal anvende ens håndtering af tidspunkter

Retningslinje GyldigFra er altid inkluderet i resultatet. GyldigTil er altid ekskluderet i resultatet. RegistreringFra er altid inkluderet i resultatet. RegistreringTil er altid ekskluderet i resultatet.

Rationale Håndtering af angivne tidspunkter skal være ens for at un-derstøtte interoperabilitet.



Implikation Webservices, som udstiller temporale ressourcer, skal desig-nes således, at serviceanvenders håndtering af tidspunkter i registrering og gyldighed altid håndteres ens.

Side 33 af 54

3.9 Sikkerhedskrav til webservices

Webservices skal kunne udveksle data sikkert og effektivt på tværs af myndighe-

der ved anvendelse af SAML 2.0 og Transport layer security.

Navn: R23. Webservices skal have tokenbaseret sikkerhed

Retningslinje Webservices skal anvende tokenbaseret sikkerhed

Rationale Fødereret adgangsstyring via tokens er en fleksibel løsning, hvor adgange mellem services synliggøres i en fødereret løsning. Håndtering af punkt til punkt forbindelser, fx ved anvendelse af certifikater, er tungt at håndtere administra-tivt.


Retningslinjen understøtter forretningsbehov F13 og F2.

Implikation Udveksling af data med webservices mellem offentlige insti-tutioner skal således anvende tokens og kan ikke opsættes som punkt til punkt forbindelser. Dog kan certifikater an-vendes til TLS.

Side 34 af 54

4. Retningslinjer for REST webservices

Retningslinjer for REST webservices er opdelt i følgende områder:

Modellering af REST webservices.

Søgning i REST webservices.

Datarepræsentation i REST webservices.

REST webservice specifikation.

REST kommunikationsprotokol.

Sikkerhedskrav til REST webservices.

4.1 Modellering af REST webservices

Serviceanvendere har typisk behov for anvendelse af udstillede webservices i

forbindelse med gennemførsel af en forretningsproces i organisationen. Forret-

ningsprocesser vil løbende ændre sig, fx på baggrund af ændrede forretningsbe-

hov, ændret lovgivning, øget eller ændret digitalisering eller modernisering af it-

løsningerne. De involverede webservices ændrer sig i takt med ændringerne til

forretningsprocesserne.

En REST webservice udstiller en ressource. En ressource er i princippet en beteg-

nelse for enhver form for information. I praksis er en ressource typisk noget, der

kan lagres på en computer som f.eks. et dokument, en række i en database, et

beregningsresultat, en mediefil mv. I kontekst af fællesoffentlig interoperabilitet

er ressourcen typisk data, men ikke nødvendigvis et objekt som persisteres. Fx

vil en webservice, der returnerer et aggreret søgeresultatet fra andre webservices,

ikke indeholde objekter, der skal persisteres. REST specificerer, jf. [FIELDING],

at visse handlinger – oprettelse, læsning, opdatering, sletning mm. kan udføres

”på” ressourcen.

Navn: R24. Udstil webservices som REST ressourcer

Retningslinje REST webservices skal udstille data som ressourcer, der kan læses og evt. oprettes, opdateres og slettes, jf. [REST].

Rationale REST arkitekturstilen fastlægger en model for webservices baseret på udstilling af ressourcer med en given datarepræ-sentation. Følges denne designmodel ikke, er den pågæl-dende webservice ikke en REST webservice, men en anden type.


Retningslinjen er affødt af forretningsbehov F6. Retningslinjen præciserer serviceprincipperne ”Services kan anvendes uafhængigt af platform” og ”Services kan anven-des uafhængigt af lokation”, jf. [OIOSVC].

Side 35 af 54

Implikation De informationer, der udstilles om ressourcen, udgør en fast aftale (eller en ”kontrakt”) mellem serviceanvender og serviceudbyder. REST arkitekturstilen opererer ikke med kontrakter (WSDL) ligesom SOAP protokollen. I praksis er serviceanvender dog afhængig af en række informationer for let at kunne anvende en webservice. Disse informatio-ner opfattes i denne sammenhæng som ”kontrakten”, uan-set at der ikke foreligger en formel specifikation som i for-bindelse med SOAP webservices. Informationerne kan in-kludere krav til sikkerhedsmodel, datarepræsentation, m.m. I stedet for at udstille funktionalitet for forretningsoperati-oner på en webservice, er det selve objekterne, der udstilles som en web ressource og hentes via verber. En ressource skal altid identificeres af en URI. De URI’er, der eksplicit udstilles til omverdenen, vil ser-viceanvendere forlade sig på. URI’er for ressourcer vil blive opfattet af serviceanvendere som en aftale mellem service-udbyder og serviceanvender. URI’er for eksplicit udstillede ressourcer kan derfor kun ændres i meget begrænset om-fang, jf. afsnit 3.4. Operationer på ressourcen er givet ved valget af kommuni-kationsprotokol til REST, se retningslinje R37. For HTTPs vedkommende er dette HTTP operationerne GET, HEAD, PUT, POST, PATCH, DELETE og OPTIONS.

I nogle situationer er det ikke data eller entiteter, der udstilles til en servicean-

vender, men en forretningsproces eller igangsætning af en forretningsproces. Et

eksempel herpå er udsendelse af et brev til en borger. I sådanne situationer bør

serviceudbyderen tilstræbe at følge REST arkitekturstilen og modellere og udstil-

le en ressource, der f.eks. repræsenterer de data, der igangsætter forretningspro-

cessen. I det konkrete eksempel med udsendelse af breve kunne serviceudbyder

udstille en service, der opretter en ny forsendelse.

Navn: R25. Udstil data som REST ressourcer

Retningslinje REST webservices udstiller data som ressourcer, der kan læses og evt. oprettes, opdateres og slettes i overensstem-melse med REST arkitekturstilen.

Rationale REST arkitekturstilen fastlægger en model for webservices baseret på udstilling af ressourcer med en given datarepræ-sentation. REST arkitekturstilen kan følges i denne situation ved at servicen modtager de data, der igangsætter forret-ningsprocessen, og udstiller dem som en ressource.

Side 36 af 54


Retningslinjen er affødt af forretningsbehov F6. Retningslinjen præciserer serviceprincipperne ”Services kan anvendes uafhængigt af platform” og ”Services kan anven-des uafhængigt af lokation” (se [OIOSVC]).

Implikation Operationer på ressourcen er givet ved valget af kommuni-kationsprotokol til REST, se retningslinje R37. Konkret betyder det f.eks. for HTTPs vedkommende, at HTTP ope-rationerne PUT, GET og DELETE f.eks. kan anvendes til at igangsætte en forretningsproces, hente status, eller stand-se forretningsprocessen.

Navn: R26. Modellér REST ressourcer med udgangspunkt i forretningsmodellering

Retningslinje REST ressourcer skal struktureres med udgangspunkt i den forretningsmodellering, der er udført efter de fællesoffentli-ge regler for begrebs- og datamodellering [MODEL].

Rationale Udstillede REST ressourcer bør struktureres ud fra den bagvedliggende forretningsmodellering. De begreber og informationsentiteter, forretningsmodelleringen af et givet domæne har afdækket, bør anses som kandidater til udstil-lede ressourcer. Forretningsmodelleringen bør være udført efter de fællesoffentlige regler for begrebs- og datamodelle-ring, jf. [MODEL]. Hvor dette ikke er tilfældet, kan ud-gangspunktet være en tilsvarende model for domænet. Modellering af ressourcer efter [MODEL] sikrer ensartet sprogbrug og fælles grundlag for at fastlægge granularitet og serviceboundaries. Det letter og tydeliggør den menneskeli-ge forståelse af funktionalitet, syntaks og semantik for en webservice, hvis webservicens design har udgangspunkt i en modellering af forretningen. Samme forståelse af informati-onen sikres hos serviceanvender og serviceudbyder, og dermed etableres semantisk interoperabilitet.


Retningslinjen er affødt af forretningsbehov F6. Retningslinjen omfatter og udvider OIO serviceprincippet ”Services understøtter forretningen”, jf. [OIOSVC].

Implikation Udstillede ressourcer skal have oprindelse i en modellering af forretningens begreber og informationer. Udgangspunktet for ressourcerne skal være forretningsmo-delleringens ”forretningsobjekter” med egenskaber. Relate-rede entiteter udstilles i udgangspunktet som separate enti-teter, jf. retningslinje R30. Forretningsmodellering kan være en konsekvens af domæ-nerelateret standardisering, f.eks. HL7/FHIR på sundheds-

Side 37 af 54

området. Der henvises til retningslinje R34 vedrørende repræsentati-on af ressourcers data.

Navn: R27. Navngiv REST ressourcer ud fra forretnings-modellens begreber

Retningslinje Navngivning af REST ressourcer skal tage udgangspunkt i den forretningsmodellering, der er udført efter de fællesof-fentlige regler for begrebs- og datamodellering [MODEL].

Rationale Et udgangspunkt i forretningsmodellens begreber sikrer ensartet navngivning og fælles grundlag for genbrug og fremsøgning. Forretningsmodelleringen afdækker forret-ningsobjekter og forklarer relationen mellem forskellige forretningsobjekter. Hvis ressourcerne, der kan tilgås via en REST webservice, anvender sigende navne, har koblingen til forretningsforståelsen et fast fundament.



Implikation Ressourcer navngives fra domænets begreber, f.eks. ”sager”, ”journalnotater”, ”parter”. Betegnelserne kan være en kon-sekvens af domænerelateret standardisering, f.eks. HL7/FHIR på sundhedsområdet. Se også retningslinje R28 vedrørende konkret navngivning.

En ressource adresseres og identificeres med en ressourceidentifikator i form af

en URI, der identificerer ressourcen og angiver, hvor ressourcen kan findes, jf.

det kommende dokument ”Retningslinjer for stabile http-URIer”.

I REST arkitekturstilen angives ressourcen som et navneord, f.eks. ”/sager” eller

”/personer”, og et ”scheme”. Her vil en typisk protokol og placeringen af res-

sourcen angives foran ressourcens navn, f.eks. ”https://it.system.dk/sager”.

Navn: R28. Navngiv REST ressourcer ud fra REST arkitek-turstilen

Retningslinje REST ressourcer skal navngives som navneord, jf. REST arkitekturstilen, og skal navngives tilsvarende serviceudstil-lers forretningsbegreber.

Rationale For at følge REST arkitekturstilen skal URI’er bestå af nav-ne på ressourcer frem for navne på operationer eller funkti-onalitet. Konkrete instanser af ressourcer kan yderligere specificeres som f.eks. ”https://it.system.dk/lokaler/123” eller ”https://it.system.dk/personer/345”.



Side 38 af 54

Implikation I overensstemmelse med REST arkitekturstilen udstilles ressourcer som en URI, der indeholder ressourcens navn. En sags ressource kunne således have en URI, der ligner ”/http://server.dk/lokaler”.

Navn: R29. Udstillede REST ressourcer har unikke, sikre identifikatorer

Retningslinje Alle udstillede REST ressourcer skal have unikke identifika-torer (URI’er), der er stabile og sikre.

Rationale REST ressourcers identifikatorer er et væsentligt element i den ”kontrakt”, en REST webservice udstiller. Hvis identi-fikatoren på en ressource ændres, vil serviceanvenderen ikke længere kunne finde den pågældende ressource. Det er der-for vigtigt, at en ressources identifikator ikke ændrer sig i løbet af ressourcens levetid. Hvis en ændring foretages, vil det kræve en kompenserende ændring hos serviceanvende-ren. Det er vigtigt, at ressourcers identifikatorer ikke inde-holder følsomme eller fortrolige informationer, eller sikker-hedsrelaterede informationer. Identifikatorerne opbevares og logges typisk i forbindelse med serviceanvendelse. Det er derfor uhensigtsmæssigt, at identifikatorerne indeholder sådanne informationer, idet logningen i så fald bliver følsom eller fortrolig. Stabile identifikatorer sikrer, at data kan genfindes i ressour-cernes levetid. REST ressourcers unikke identifikatorer skal være unikke, hvilket betyder, at de kun må udpege én ressource. Det skal være muligt for serviceanvendere at opbevare ud-stillede ressourcers identifikatorer. Identifikatorerne skal være sikre, hvilket betyder, at de ikke må indeholde personoplysninger, da identifikatorerne typisk vil indgå i den krævede logning af adgang til ressourcen, jf. retningslinje R13.



Implikation Serviceudbyderen er selv ansvarlig for at definere identifika-toren for en givet ressource. Identifikatoren skal være en HTTP-URI og kan være en HTTP-URI, som indeholder et UUID. Personnumre kan ikke anvendes som unikke identi-fikatorer, da en persons personnummer kan ændre sig i personens levetid. Logning af en person (ressources) URI, der indeholder et personnummer, medfører, at logningen indeholder personoplysninger, og dermed underlægges reg-

Side 39 af 54

ler om sletning, der vanskeligt kan håndhæves.

Navn: R30. Udstil REST ressourcers relaterede entiteter

Retningslinje REST ressourcer skal udstilles sine entiteter ved at følge de fællesoffentlige regler for begrebs- og datamodellering [MODEL]. Relationer til entiteter som udstilles af andre webservices skal udstilles ved at følge de fællesoffentlige regler for be-grebs- og datamodellering [MODEL].

Rationale Entiteter, der udstilles som REST ressourcer, vil ofte have relationer til andre entiteter. Relaterede entiteter bør udstilles som separate (un-der)ressourcer, som kan tilgås direkte ved brug af en pas-sende identifikator (URI). Serviceanvendere gives dermed mulighed for at tilføje, ændre eller fjerne relaterede entiteter uden at skulle opdatere hele ressourcen. REST ressourcer repræsenterer begreber i forretningsmo-delleringen. Forretningsmodelleringen afdækker relationer mellem entiteter. Disse relationer bør kunne tilgås som un-derressourcer, jf. REST arkitekturstilen, og gøre det forstå-elsesmæssigt lettere og teknisk mere effektivt at anvende webservicen.



Implikation REST webservices bør udstille relaterede forretningsobjek-ter som underressourcer, f.eks. ”/sager/<sagsid>/journalnotater/<notatid>”. Navngivningen af underressourcen bør følge navne fra mo-delleringen, jf. retningslinje R27.

REST arkitekturstilen fastlægger, at hypertext, dvs. indhold med aktive links der

kan navigeres efter, er måden, hvorpå ressourcer tilgås. REST webservices bør

derfor informere om sig selv og om relevante andre ressourcer via hypertext

links.

Navn: R31. Returnér REST ressourcer med hypertext links

Retningslinje REST ressourcer skal returnere hypertext links til alle rele-vante informationer om ressourcen, når ressourcen tilgås, jf. REST arkitekturstilen.

Rationale REST webservices udstiller eksplicit en række ressourcer med velkendte URI’er. I det omfang relaterede objekter udstilles via hypertext links, er det en fordel for serviceud-

Side 40 af 54

byderen ikke at forpligte sig til disse hypertext links’ værdi-er. Serviceanvenderen bør ikke opbevare URI’erne til relate-rede objekter, men skal fremfinde dem hver gang, hvilket giverserviceudbyderen bedre muligheder for at foretage ændringer, uden at serviceanvenderen påvirkes. REST arkitekturstilen [HATEOAS] samt [MATURITY] påpeger, at REST webservices skal returnere metainforma-tioner om ressourcer via hypertext links. Hvis ressourcer returnerer relevante links som metadata, behøver servicean-vendere ikke at kende de konkrete links på forhånd. Dette giver serviceudviklere frie hænder til at ændre URI’er på de forretningsobjekter, der ikke direkte er udstillet til service-anvendere.



Implikation REST ressourcer bør returnere deres egen URI, links til en specifikation af deres repræsentation, links til formidling af URI’er til relaterede objekter, og links til de operationer ressourcen aktuelt understøtter. Disse links bør returneres ved for hvert link at angive linket med dets relation6 til res-sourcen.

4.2 Søgninger i REST webservices

REST webservices vil ofte udstille ressourcer, der er samlinger af forretningsob-

jekter, f.eks. forvaltningssager, aktører, eller dokumenter. Serviceanvenderne har

typisk ikke brug for altid at hente alle de konkrete instanser, og har derfor behov

for at forespørge, hvis ikke URI’en for den konkrete instans er kendt på forhånd.

Navn: R32. Anvend standardiserede REST fremsøgnings-parametre

Retningslinje REST webservices skal understøtte standardiserede frem-søgningsparametre i det omfang, søgning understøttes af webservicen.

Rationale En REST webservice, der understøtter søgning skal under-støtte at ressourcens URI kan suppleres med ”parametre” til søgning eller sortering, der anvendes ved læsning af res-sourcer (ved brug af HTTP GET). Søgeparametrene kan understøtte, at der angives værdier for ønskede attributter eller tilstedeværelsen af relationer. Når de udvalgte konkrete instanser er fremsøgt, kan servicean-

6 En fællesoffentlig standard kan evt. fastlægges for at sikre ensartethed.

Side 41 af 54

venderen have behov for at angive en sortering eller en præcisering af, hvilke informationer serviceanvenderen har brug for. Standardiserede søgeparametre på tværs af fælles-offentlige webservices vil gøre det forståelsesmæssigt lettere at anvende sådanne webservices. For at gøre det lettere at anvende en webservice for service-anvendere, skal fremsøgninger i samlinger af forretningsob-jekter anvende standardiserede søgeparametre. Ensretning af parametrene betyder, at serviceanvendere kan genbruge eksisterende erfaringer med søgning.



Implikation Standardiseringen bør inkludere parametre for udvælgelse (query), sortering af resultater, selektion af returnerede at-tributter for fremsøgte ressourcer, samt information om hvorvidt relaterede ressourcer skal returneres. Understøttelsen af søgning skal dog afvejes over for ret-ningslinje R01 om at minimere funktionalitet og målrette webservices.

Søgning i ressourcer angives i URI som en query string med ”søgeoperator” ’q’ (dvs. ”?q=alder%3d20”).

Sortering ved ressourcesøgninger angives i URI som query string med ”søgeoperator” ’sort’ (dvs. ”?sort=alder”).

Selektering af attributter ved ressourcesøgninger an-gives i URI som query string med ”søgeoperator” ’fields’ (dvs. ”?fields=navn,adresse”).

Embedding af relaterede objekter ved ressourcesøg-ninger angives i URI som query string med ”søge-operator” ’embed’ (dvs. ”?embed=barn”).

De faktisk understøttede søgemuligheder skal målrettes de faktiske behov, jf. retningslinjerne R01.

Når serviceanvendere bruger REST webservices, der udstiller samlinger med

mange objekter, vil serviceanvenderen typisk ønske at kunne fremsøge objekter-

ne gradvist for at forbedre svartider på søgning. En REST webservice kan un-

derstøtte dette ved at tillade ”paginering” (søgeresultater kan indlæses ”sidevist”).

Paginering er en velkendt teknik, hvor webservicen giver serviceanvenderen mu-

lighed for at indikere et antal ønskede objekter, samt hvorfra søgningen skal

”fortsætte”.

Side 42 af 54

Navn: R33. Understøt søgning med delresultater

Retningslinje REST webservices, der udstiller store samlinger af forret-ningsobjekter, skal understøtte paginering i forbindelse med den søgning, webservicen understøtter.

Rationale Webservices kan indeholde et stort antal objekter og relate-rede objekter. Webservicen bør i de tilfælde understøtte delvis afhentning af søgeresultater (dvs. paginering), så serviceanvender ikke altid modtager hele søgeresultatet.



Implikation Webservices, der tilgår store mængder af objekter, bør un-derstøtte pagineringsparametre under fremsøgning. Pagine-ringen bør anvende en eksplicit ”cursor” (f.eks. elementi-dentifikator eller position), der skal medsendes fra service-anvenderen. Serviceudbyderen kan lade sig inspirere af in-ternet RFC 50057. Det samlede antal objekter, der udgør søgningens resultat bør medsendes, hvis dette kendes af webservicen. Serviceudbyderen bør dokumentere, hvordan pagineringen påvirkes, hvis der sker ændringer til samlingen af objekter, mens pagineringen pågår. De understøttede muligheder for paginering skal målrettes de faktiske behov, jf. retningslinjerne R01.

4.3 Datarepræsentation i REST webservices

REST webservices kan i princippet udstille ressourcers data med en vilkårlig

datarepræsentation. I praksis repræsenteres ressourcer ofte i JSON-format eller

som et XML dokument.

JSON vurderes både generelt velegnet, og i sammenligning med XML særlig

velegnet, når behovet er kommunikation med en webbrowser. JSON-formatet

har yderligere den fordel, at det er relativt kompakt.

Navn: R34. Repræsentér REST ressourcer i et standardise-ret dataformat

Retningslinje REST ressourcers data skal repræsenteres i JSON eller

7 Se f.eks.: https://tools.ietf.org/html/rfc5005

https://tools.ietf.org/html/rfc5005

Side 43 af 54

XML. Webservicen skal returneres i det format, som ser-viceanvenderen ønsker, hvis det er muligt.

Rationale XML har stor udbredelse i fællesoffentlige webservices (der konkret udstilles som SOAP services). Mange udviklings-teknologier understøtter validering af XML (specificeret via XSD), og udstilling som domæneobjekter i programme-ringssproget (via autogenereret kode). Det vurderes dog vigtigst, at den repræsentation, en res-source udstilles med, er relevant for forretningsdomænet. Nogle domæner som fx geodataområdet og sundhedsområ-det har i væsentligt omfang egne standarder (henholdsvis OGC og HL7/FHIR). En domænespecifik, standardiseret repræsentation foretrækkes derfor, da de syntaktiske og semantiske forhold ofte er afklarede og veldokumenterede. Hvis der på et forretningsområde ikke findes en standard for datarepræsentation, er JSON eller XML velegnet som generel datarepræsentation, da mulighederne for repræsen-tation af komplekse datastrukturer normalt er tilstrækkelige i disse formater. Serviceudbyderen skal udstille data til serviceanvendere. Hvis der til data findes datastandarder inden for serviceud-byderens domæne – f.eks. HL7/FHIR for sundhedsdomæ-net – bør disse anvendes for at sikre, at serviceanvender har et veldefineret grundlag for at forstå data.


Retningslinjen er affødt af forretningsbehov F6, F8, F9 og F2.

Implikation Hvis et domænerelateret dataformat er anvendeligt, bør webservices anvende dette. Ved standardiseret dataformat forstås i denne forbindelse også dataformater, der har bred anvendelse men ikke formelt er standardiserede. Der bør i denne forbindelse tages hensyn til, om et givet standardise-ret dataformat er velegnet til transmission via REST og HTTP.

Navn: R35. Deklarér REST ressourcer datarepræsentationer

Retningslinje REST ressourcer skal i deres kommunikation deklarere, hvilke datarepræsentationer (f.eks. JSON, XML), de under-støtter.

Rationale Hvis en REST ressource deklarerer de understøttede repræ-sentationer, er det muligt for serviceanvenderen at vælge

Side 44 af 54

den bedst egnede, således at webservicen målretter sig ser-viceanvenderens behov.



Implikation REST webservices skal udstille og deklarere, hvilken data-repræsentation de tilgængelige ressourcer har. REST web-services, der tilgås via HTTP, har yderligere den mulighed, at alternative datarepræsentationer kan tilbydes. En ressour-ce kan således deklarere, at den udstiller både JSON og XML. En serviceanvender kan ved adgang til ressourcen via HTTP indikere hvilke repræsentationer, der foretrækkes (med prioritering). REST ressourcer bør via en HTTP header altid tilkendegi-ve, hvilke repræsentationer ressourcen understøtter, når ressourcen returneres fra serviceudbyderen, fx ved et opslag eller en opdatering.

Når REST webservices udstiller tekst – navne, beskrivelser, mv. – ,er det vigtigt,

at tekstens individuelle tegn overføres korrekt, især i forhold til de danske speci-

altegn ’æøå’, men også tegn der ofte anvendes i navne, f.eks. ’äëöüé’. Tekstkod-

ning er ofte en udfordring med især ældre it-løsninger, der udstiller webservices,

eller når data fra en database udstilles direkte.

Navn: R36. Overfør tekst i en internationaliseret repræsen-tation

Retningslinje Tekst, herunder navne, beskrivelser mm. skal overføres mellem serviceanvender og serviceudbyder i et internationa-liseret overførselsformat, UTF-8 eller tilsvarende, med min-dre en anvendt domænespecifik standard tilsiger andet.

Rationale De danske specialtegn samt tegn fra EU og andre lande anvendes bredt i webservices. Serviceudbyder og servicean-vender skal vide sig sikre på, at tegn overføres korrekt. UTF-8 standarden skal anvendes hertil, da den sikrer kor-rekt overførsel og er i stand til at repræsentere alle nødven-dige tegn.



Implikation Udstillede webservices skal sikre, at tekst, der skal returne-res til eller modtages fra serviceanvender, konverteres, så-fremt teksten ikke efterfølgende opbevares og behandles i UTF-8. Hvis teksten skal konverteres, er webservicen an-svarlig for konverteringen. En undtagelse i denne forbindelse er, hvis en domænespeci-

Side 45 af 54

fik standard, der anvendes til webservicens datarepræsenta-tion, fastlægger et andet format.

4.4 REST kommunikationsprotokol

REST arkitekturstilen kræver ikke HTTP, men HTTP er den mest anvendte

kommunikationsprotokol til REST webservices. HTTP er velegnet til REST

webservices, og der findes væsentlig værktøjs- og teknologiunderstøttelse af

REST via HTTP.

HTTP består af en request struktur og en response struktur. I request strukturen

angiver serviceanvenderen HTTP metoden (verbet), der skal gøre noget ved res-

sourcen, som er udpeget vha. en URI. I request headeren angives desuden para-

metre og andre metadata for forespørgslen. Eksempelvist kan der vha. authori-

zation vedlægges et sikkerhedstoken. Det kan også være parametre for cache,

tekstkodning, dato mv. I request body angives en evt. inputstruktur for kaldet.

I response-strukturen angives en HTTP statuskode. I response headeren angives

parametre og metadata for svaret. I response body sendes ressourcens repræsen-

tation, som er det faktiske beskedindhold, typisk i form af en XML eller JSON-

struktur. Den returnerede repræsentation af ressourcen bør afgøres vha. content

negotiation, der er en HTTP mekanisme for at aftale formatet på de overførte

data, jf. retningslinje R38.

Navn: R37. Anvend HTTP som fællesoffentlig REST kommunikationsprotokol

Retningslinje REST webservices skal anvende HTTP som kommunikati-onsprotokol ved kald fra serviceanvender til den udstillede webservice og følge Bilag 4 ”Specifikation for brug af HTTP til REST”

Rationale HTTP protokollen er standardiseret, og generelt anbefalet i forbindelse med udstilling af REST webservices. HTTP protokollen har tilstrækkelig funktionalitet til at understøtte behovene for overførsel/transmission af data i forbindelse med kald af webservices.


Retningslinjen er affødt af forretningsbehov F1, F6 og F8. Retningslinjen præciserer OIO serviceprincippet ”Services baseret på standarder”, jf. [OIOSVC].

Implikation REST webservices skal overholde de krav til anvendelse af http metoder og headerinformation i kald og svar, som er beskrevet i Bilag 4 ”Specifikation for brug af HTTP til REST”

Side 46 af 54

HTTP indeholder en række mekanismer, der bidrager til effektiv brug af bånd-

bredde, datarepræsentation, mv. Disse mekanismer skal anvendes af servicean-

vender og serviceudbyder for at sikre effektiv kommunikation.

Navn: R38. Anvend HTTPs mekanismer til effektiv kom-munikation

Retningslinje Serviceudbyderen skal anvende HTTP således, at effektiv kommunikation med REST webservices understøttes.

Rationale Hvis serviceudbyderen tillader brug af bestemte HTTP-mekanismer, kan kommunikationen mellem serviceanven-der og serviceudbyder effektiviseres. Understøttelse af for-handling af ønsket datarepræsentation mellem webservicen og serviceanvenderen målretter webservicen til den konkre-te brug. Understøttelse af komprimering af forespørgsel og svar reducerer krav til netværksbåndbredden.



Implikation http standardens ”content negotiation” mekanisme anven-des for at aftale datarepræsentation mellem serviceanvender og serviceudbyder. HTTP kompression af forespørgsler og svar skal understøt-tes, eventuelt implementeret i selve HTTP serveren8.

Navn: R39. Anvend HTTP sikkert til REST ressourcer

Retningslinje REST webservices skal anvende HTTP sikkert ved udstil-ling af ressourcer.

Rationale REST webservices skal sikre anvendelse af HTTP. Webser-vices skal kræve sikre forbindelser, f.eks. HTTPS eller kryp-tering og autentifikation via en anden mekanisme. De URI’er, der anvendes til ressourcer, bør ikke indeholde for-trolige eller følsomme data. Logning af HTTP logger den tilgåede URI, og dermed kan fortrolige eller følsomme data persisteres i HTTP infrastrukturens logning. Endelig skal det sikres, at eventuelle HTTP servere, der er placerede ”foran” udstillede webservices, ikke logger den dynamiske del af URI’en (query string), da en søgning even-tuelt kunne søge på følsomme eller fortrolige data (f.eks. personnummer). Serviceudbyderen skal tilskynde, at HTTP anvendes på en

8 Flere gængse HTTP servere kan opsættes til komprimering og dekomprimering af data, f.eks. Apache HTTPd.

Side 47 af 54

sikker måde af serviceanvenderen. Dette kan serviceudby-deren gøre ved bl.a. at kræve sikker, det vil sige krypteret og autentificeret HTTP, og ved at sikre at URI’er ikke i sig selv indeholder følsomme eller fortrolige data.



Implikation Webservices bør returnere specifikke fejlkoder, hvis ser-viceanvenderen bruger usikker HTTP (dvs. uden kryptering og autentificering) i stedet for automatisk at omstille ser-viceanvenderen til en sikker HTTP. REST webservices bør kun udstille URI’er, der ikke inde-holder nøgler af følsom karakter, f.eks. personnumre eller sikkerhedsinformationer. Hvis udstillede REST webservices anvender en foranstillet HTTP server, må denne ikke logge HTTP ”query string” eller andre evt. følsomme eller fortrolige data, da denne logning ellers skal hånderes som følsomme data.

4.5 Sikkerhedskrav til REST webservices

Navn: R40. REST webservices skal anvende OIO IDWS REST profile V1.0

Ret-ningslin-je

REST Webservices skal anvende OIOIDWS REST profile 1.0 ved håndtering af data

Rationale HTTP og REST arkitetkturstilen angiver ikke entydigt, hvorledes SAML tokens udveksles. REST service skal anvende OIOIDWS REST profile 1.0, således at SAML tokens angives ensartet og med de ønskede metadata. Angivelse af SAML information i HTTP kan medføre problemer med platformsunderstøttelse. Anvendelse af OIOIDWS REST pro-file 1.0 sikrer, at SAML understøttelsen virker på tværs af udvik-lingsplatforme. OIO IDWS REST Profile 1.0 : https://www.digitaliser.dk/resource/526486/artefact/OIOIDWSRESTprofileV1_0.pdf?artefact=true&PID=3066971

Under-støttede forret-ningsbe-hov

F13, F2

Implika- Retningslinjen sikrer, at SAML implementeringen i REST webser-

https://www.digitaliser.dk/resource/526486/artefact/OIOIDWSRESTprofileV1_0.pdf?artefact=true&PID=3066971

https://www.digitaliser.dk/resource/526486/artefact/OIOIDWSRESTprofileV1_0.pdf?artefact=true&PID=3066971

Side 48 af 54

tion vices er ensartet på tværs af serviceudbydere, hvilket giver bedre interoperabilitet for serviceanvendere, som tilgår mange offentlige services. Profilen indeholder mulighed for at medsende identifikati-on på serviceanvenderen eller brugeren hos serviceanvenderen. Det er ikke et krav, at identiteter altid medsendes, men serviceanvender og serviceudbyder kan vælge at medsende identiteten ved kald til services eller anvende en systembruger.

Side 49 af 54

5. Referenceliste

ID Kilde

[FODS] Digitaliseringsstyrelsen (2016) Den fællesoffentlige digitaliseringsstrategi 2016-2020,. Tilgængelig på: https://www.digst.dk/Strategier/Strategi-2016-2020

[FIEL-DING]

Roy Thomas Fielding (2000)Architectural Styles and the Design of Network-based Software Architectures.

[HVID-BOG]

Digitaliseringsstyrelsen (2017)Den digitalt sammenhængende offentlige sektor – Hvidbog om arkitektur for digitalisering, version 1.0.. Tilgænge-lig på: http://arkitektur.digst.dk/mandat-og-styring/hvidbog-om-faellesoffentlig-digital-arkitektur

[MATU-RITY]

Leonard Richardson (2008) Richardsons maturity model, Tilgængelig på: https://martinfowler.com/articles/richardsonMaturityModel.html

[MODEL] Digitaliseringsstyrelsen (2017) Fællesoffentlige regler for begrebs- og da-tamodellering, version 1.0. Tilgængelig på: https://arkitektur.digst.dk/metoder/regler-begrebs-og-datamodellering

[OIO-IDWS]

Digitaliseringsstyrelsen (2016) OIO IDWS REST profile, version 1.0. Tilgængelig på: https://digitaliser.dk/resource/526486/artefact/OIOIDWSRESTprofileV1_0.pdf?artefact=true&PID=3066971

[OIOMØNSTRE]

Digitaliseringsstyrelsen (2014)”Integrationsmønstre. Tilgængelig på http://arkitekturguiden.digitaliser.dk/integrations-moenstre

[OIO-REST]

It- og Telestyrelsen (2009) OIOREST i praksis – guidelines baseret på eksempler.,

[OIOSVC] Digitaliseringsstyrelsen (2014)Serviceprincipper”, . Tilgængelig på: http://arkitekturguiden.digitaliser.dk/serviceprincipper

[RE-GEL7.1]

Digitaliseringsstyrelsen (2017) Arkitekturregel 7.1: Design og udstil snitflader efter fælles integrationsmønstre og tekniske standarder. Tilgængelig på: http://arkitektur.digst.dk/principper-og-regler/princip-7-it-loesninger-samarbejder-effektivt/arkitekturregel-71-design-og

[W3C] W3C Working Group (2004) Definition af webservices og relation til REST. Tilgængelig på: http://www.w3.org/TR/ws-arch/#relwwwrest

https://www.digst.dk/Strategier/Strategi-2016-2020

http://arkitektur.digst.dk/mandat-og-styring/hvidbog-om-faellesoffentlig-digital-arkitektur

http://arkitektur.digst.dk/mandat-og-styring/hvidbog-om-faellesoffentlig-digital-arkitektur

https://martinfowler.com/articles/richardsonMaturityModel.html

https://arkitektur.digst.dk/metoder/regler-begrebs-og-datamodellering

https://arkitektur.digst.dk/metoder/regler-begrebs-og-datamodellering

https://digitaliser.dk/resource/526486/artefact/OIOIDWSRESTprofileV1_0.pdf?artefact=true&PID=3066971

https://digitaliser.dk/resource/526486/artefact/OIOIDWSRESTprofileV1_0.pdf?artefact=true&PID=3066971

http://arkitekturguiden.digitaliser.dk/integrations-moenstre

http://arkitekturguiden.digitaliser.dk/serviceprincipper

http://arkitektur.digst.dk/principper-og-regler/princip-7-it-loesninger-samarbejder-effektivt/arkitekturregel-71-design-og

http://arkitektur.digst.dk/principper-og-regler/princip-7-it-loesninger-samarbejder-effektivt/arkitekturregel-71-design-og

http://www.w3.org/TR/ws-arch/#relwwwrest

http://www.w3.org/TR/ws-arch/#relwwwrest

Side 50 af 54

6. Appendiks A Eksempel på anvendelse

I det følgende anskuliggøres retningslinjerne for webservices anvendelse af

REST ved brug af et eksempel om lokalebooking.

Lokalestyrelsen ønsker at udstille en webservice til lokalebooking. Der er følgen-

de funktionalitet og data:

Som medarbejder skal jeg kunne se en liste af tilgængelige mødelokaler for et givent tidspunkt.

Som medarbejder skal jeg kunne oprette en ny booking i et givent møde-lokale og angive tidsrummet, hvor mødet kan finde sted, for at kunne af-holde et internt eller eksternt møde.

Som mødeadministrator skal jeg kunne se, hvornår en booking er foreta-get, samt hvornår den skal gælde fra og til.

Jf. retningslinjerne skal ressourcer udstilles som navneord og svare til forret-

ningsmodelleringens begreber.

”Lokaler” er således en liste over styrelsens mødelokaler.

”Bookinger” er en liste over et mødelokales bookinger.

Her kunne man vælge, om sammenhængen mellem lokaler og bookinger omfat-

ter, at en booking kunne omfatte flere mødelokaler. I dette tilfælde vælger styrel-

sen, at en booking kun kan omfatte ét lokale.

Det giver følgende URI’er for afhentning af ressourcer:

Funktion URI

Hent loka-ler

GET http://lokalebooking.dk/ressourcer/lokaler/

Hent lo-kale

http://lokalebooking.dk/ressourcer/lokaler/[ID]

Hent bookinger for et loka-le

http://lokalebooking.dk/ressourcer/lokaler/[ID]/bookinger

Hent en booking

http://lokalebooking.dk/ressourcer//lokaler/[ID]/bookinger/ID

Et møde har Tidsrum er fra og til og Registreringstid er egenskaber ved en booking.

http://lokalebooking.dk/ressourcer/lokaler/

http://lokalebooking.dk/ressourcer/lokaler/%5bID

http://lokalebooking.dk/ressourcer/lokaler/%5bID%5d/bookinger

http://lokalebooking.dk/ressourcer/bookinger/ID

Side 51 af 54

Opdateringer af ressourcer kan ske som oprettelser, hvor serviceanvenderen kan

angive et id, således at en serviceanvender fx kan knytte andre ressourcer fx

agenda til en booking. Derfor anvendes PUT verben og ikke POST.

Tilsvarende kan deltaopdateringer ikke udføres, hvorfor der ikke understøttes

PATCH.

6.1 Avendelse af temporalitet

For at overholde retningslinjerne for webservices, designes lokalebookingser-

vicen desuden med følgende temporale dimensioner:

1. Det er kun muligt at booke et lokale, såfremt det er ledigt på bookingtids-punktet.

2. Det er ikke muligt at booke et lokale bagud i tid. 3. Det er kun muligt at booke et lokale maksimalt to timer ad gangen. 4. Der skal være minimum tre timer mellem møder, som brugeren ønsker at

booke til.

For at sikre integritet af bookingerne, designes servicen med en operation

’Booking’:

http://lokalebooking.dk/ressourcer/lokaler/<id>/bookinger/<id>

Booking kan kaldes med HTTP Put med følgende parametre:

lokaleId=[String].

GyldigFra= [dateTime].

GyldigTil = [dateTime].

Servicen validerer ved servicekaldet, om lokaleId er gyldigt for hele perioden

[GyldigFra;GyldigTil], hvor lokalet ønskes booket. Desuden validerer servicen, at

det pågældende lokale er ledigt i hele perioden, og at perioden ikke overskrider to

timer. Endeligt validerer servicen om den pågældende bruger, som foretager lo-

kalebookingen, ikke har en booking på dette eller andre lokaler inden for tre ti-

mer af GyldigTil tidspunktet. Hvis disse betingelser er opfyldt, opretter Servicen

en ny bookingressource og returnerer 200, hvis ikke returneres en fejlkode.

Det er dermed muligt at oprette en booking, som overholder alle temporale for-

retningsregler og har indkapslet denne logik over for serviceanvendere. Dermed

overholdes retningslinje R18.

Servicen skal kunne forespørge, om et lokale er ledigt for en given periode, hvor-

for der er behov for at kunne fremsøge dette på en given lokaleressource. Hertil

anvendes HTTP GET:

http://lokalebooking.dk/ressourcer/booking

Side 52 af 54

GET

http://lokalebooking.dk/ressourcer/Lokaler/[id]/bookinger?GyldigFra>=[tidsp

unkt]&GyldigTil<[tidspunkt]

Ovenstående servicekald returnerer alle bookinger, som er foretaget på et givent

lokale i den angivne periode. Hvis svaret fra servicen er 204 (no content), bety-

der det, at lokalet er ledigt på det pågældende tidspunkt.

Hvis søgeparametrene GyldigFra og GyldigTil ikke var angivet, ville servicen

have returneret default-svar svarende til at GyldigFra=NU og GyldigTil=NU.

Svaret ville dermed angive, om lokalet er ledigt på tidspunktet for forespørgslen,

men ikke hvor lang tid frem. Endelig skal servicen udstille en flade for bookinger

på et lokale. Dette udstilles som en særskilt ressource i forhold til bookingres-

sourcen:

http://lokalebooking.dk/ressourcer/lokaler/[id]/flade/

Servicen skal kunne fremfinde tidligere registreringer, således at der er fuld spor-

barhed på bookinger (oprettelser, ændringer og aflysninger), som er foretaget på

et givent lokale.

Det er muligt at angive søgeparametre på flade:

http://lokalebooking.dk/ressourcer/lokaler/[id]/flade/?RegistreringsTidspunkt

=[tidspunkt]

Herved returneres indholdet af den seneste registrering inden [tidspunkt.]

En anden mulighed for at angive søgeparametre på flade er som følger

http://lokalebooking.dk/ressourcer/lokaler/[id]/flade/?RegistreringsTidspunkt

Fra=[tidspunkt]&RegistreringsTidspunktTil[tidspunkt]

Herved returneres en liste af bookinger svarende til samtlige registreringer i in-

tervallet.

http://lokalebooking.dk/ressourcer/Lokaler/%5bid%5d/bookinger?GyldigFra=%5btidspunkt%5d&GyldigTil%5btidspunkt

http://lokalebooking.dk/ressourcer/Lokaler/%5bid%5d/bookinger?GyldigFra=%5btidspunkt%5d&GyldigTil%5btidspunkt

http://lokalebooking.dk/ressourcer/lokaler/%5bid%5d/revisionsspor

http://lokalebooking.dk/ressourcer/lokaler/%5bid%5d/flade/?RegistreringsTidspunkt=%5btidspunkt

http://lokalebooking.dk/ressourcer/lokaler/%5bid%5d/flade/?RegistreringsTidspunkt=%5btidspunkt

http://lokalebooking.dk/ressourcer/lokaler/%5bid%5d/flade/?RegistreringsTidspunktFra=%5btidspunkt%5d&RegistreringsTidspunktTil%5btidspunkt

http://lokalebooking.dk/ressourcer/lokaler/%5bid%5d/flade/?RegistreringsTidspunktFra=%5btidspunkt%5d&RegistreringsTidspunktTil%5btidspunkt

Side 53 af 54

7. Appendiks B Liste over retningslinjer:

R01. Udstil minimal funktionalitet og data i den enkelte webservice R02. Separér webservices fra konkret implementering R03. Separér webservices fra eksterne afhængigheder R04. Understøt gentagne forsøg på kald fra serviceanvenderen R05. Kræv specifikke informationer ved ansvarsoverdragelse ved kald til webservices R06. Dokumentér udstillede webservices i overensstemmelse med den

fællesoffentlige dokumentationsramme for webservices R07. Opmærk webservices i henhold til fællesoffentlige emnesystematikker R08. Opmærk webservices med følsomhed eller fortrolighed af data R09. Dokumentér servicespecifikke fejlkoder for webservices R10. Dokumentér drift af forskellige versioner af webservices R11. Anvend semantisk versionering af webservices R12. Viderefør gamle versioner, når en webservice ændres R13. Log alle kald til webservices R14. Anvend transaktionsidentifikatorer ved kald og svar R15. Anvend requestID ved kald og svar R16. Understøt monitorering af udstillede webservices R17. Returnér servicespecifikke fejl som standardiserede fejlmeddelelser R18. Forretningsregler vedrørende temporaler indkapsles og håndhæves på

serviceniveau R19. Webservices med temporale ressourcer returnerer som et øjebliksbillede R20. Webservices med temporale ressourcer anvender anerkendte nøgleord i

søgeparametre. R21. Webservices med temporale ressourcer skal udstille ensartet funktionalitet til

revision og Linje R22. Webservices med temporale ressourcer skal anvende ens håndtering af

tidspunkter R23. Webservices skal have tokenbaseret sikkerhed R24. Udstil webservices som REST ressourcer R25. Udstil data som REST ressourcer R26. Modellér REST ressourcer med udgangspunkt i forretningsmodellering R27. Navngiv REST ressourcer ud fra forretningsmodellens begreber R28. Navngiv REST ressourcer ud fra REST arkitekturstilen R29. Udstillede REST ressourcer har unikke, sikre identifikatorer R30. Udstil REST ressourcers relaterede entiteter R31. Returnér REST ressourcer med hypertext links R32. Anvend standardiserede REST fremsøgningsparametre R33. Understøt søgning med delresultater R34. Repræsentér REST ressourcer i et standardiseret dataformat R35. Deklarér REST ressourcer datarepræsentationer R36. Overfør tekst i en internationaliseret repræsentation R37. Anvend HTTP som fællesoffentlig REST kommunikationsprotokol R38. Anvend HTTPs mekanismer til effektiv kommunikation R39. Anvend HTTP sikkert til REST ressourcer R40. REST webservices skal anvende OIO IDWS REST profile V1.0

arkitektur.digst.dk

Documents

Fælles retningslinjer for webservices...Webservices skal have en entydig mekanisme til ansvarsoverdragelse mel-lem myndigheder, således at der altid er klarhed over, hvilken myndighed