Diaz spill & lunsjbar, Geilo - Restaurantanmeldelser - TripAdvisor\nDiaz spill & lunsjbar, Geilo\nNr. 6 af 21 Restauranter i Geilo\nVesleslaattvegen 19, Geilo 3580, Norge\nPizza, Café, Grill, Spisested, Supper\nVi stoppede her til frokost på vores 7 timers road trip fra Bergen til Oslo. Fødevarer er velsmagende og god del. Rene og hyggelige omgivelser. Der er et par interessante butikker, der sælger tøj og husholdningsartikler ud over denne butik.\nVi holdt en uge i Geilo gennem de restauranter, der havde fået de bedste punkter i Tripadvisor. Det betød, at vi besøgte steder fra enkle cafeer til den eneste fine spisestue slags sted i byen. Selvom jeg tager mad seriøst, vurderer jeg normalt kun hoteller...- restauranter kun hvis jeg tror at jeg mærker noget ud over det sædvanlige. Denne gang er kombinationen af smag af mad (især i forhold til den overkommelige prisfastsættelse: Så forvent ikke god spisning, men maden er velforberedt og velsmagende) i kombination med serviceniveauet gjorde mig opmærksom på dette sted at du. Jeg har gjort min karriere i kundeforretningsbranchen, og jeg ved, hvor svært det er at finde balancen mellem høflig, venlig, opmærksom og alligevel ikke seriøs serice, men parret runnig denne restaurabt vidste sikkert hvordan man gør det. Må ikke modløses af frot døren - det ligner en kiosk, men restauranten del er komfortable og udsigten meget flotMere\nFå hurtige svar fra personale og tidligere besøgende på Diaz spill & lunsjbar.\nSiddepladser, Handikapvenlig, Vin og øl, Tager imod kreditkort\nAdresse: Vesleslaattvegen 19, Geilo 3580, Norge\nTelefonnummer: +47 32 09 09 82


Retningslinjer for webservices | Fællesoffentlig Digital Arkitektur\nDette dokument beskriver fællesoffentlige retningslinjer for anvendelse af webservices 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.\nRetningslinjerne er udsprunget af ”Hvidbog om arkitektur for digitalisering” (jf. [HVIDBOG]), hvor retningslinjerne er en konkretisering af princip 7 og arkitekturregel 7.1 . Princip 7 tilsiger, at it-løsninger samarbejder effektivt, mens arkitekturregel 7.1 tilsiger, at der skal designes og udstilles snitflader efter fælles integrationsmønstre og tekniske standarder\nDe fælles retningslinjer for webservices i dette dokument er en vejledning til serviceudbydere, der skal udstille data og funktionalitet via webservices. Vejledningen skal opfattes som en beskrivelse af god praksis og skal hjælpe serviceudbyderen, når denne designer og udstiller webservices rettet imod serviceanvendere.\nWebservices er defineret som angivet i [W3C]: “A Web service is a software system designed to support interoperable machine-tomachine 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:\narbitrary Web services, in which the service may expose an arbitrary set of operations.“\nREST er en arkitekturstil, der anvendes til udstilling af ressourcer (data) med webservices. REST er baseret på principperne og arkitekturen, som anvendes på internettet, og genbruger få, udbredte standarder og protokoller herfra, f.eks. HTTP. [FIELDING].\nEn række domæner har i dag allerede domænespecifikke retningslinjer og standarder, fx på sundhedsområdet. Det er væsentligt, at anvendelsen af retningslinjerne 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 anvendelige, hvor der ikke foreligger domænespecifikke standarder og retningslinjer for webservices.\nRetningslinjerne har følgende væsentlige afgrænsninger:\nRetningslinjerne stiller ikke krav til, at offentlige institutioner skal anvende REST over andre arkitekturstile, når data og funktionalitet skal udstilles via webservices.\nServiceanvendere kan have behov for at kalde mere end én webservice. Et eksempel herpå er en serviceanvender, som skal foretage en opdatering 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 serviceorkestrering, da det indeholder designvalg omkring processer og orkestrering, som ikke er en del af retningslinjernes område.\nRetningslinjerne stiller ikke krav om hvornår temporaler generelt skal anvendes i webservices, dette er serviceudstillers beslutning, retningslinjer stiller således kun krav til hvordan webservices udstiller temporaler.\nRetningslinjerne stiller krav til logning i forbindelse med webservicens anvendelse, og dokumentet indeholder ikke retningslinjer, som sikrer overholdelse af bestemt lovgivning, fx GDPR.\nRetningslinjerne i dette dokument kan den enkelte organisation vælge at anvende inden for egen organisation for at skabe mere ensartede snitflader på tværs af it-løsninger, men det er ikke et krav.\nDokumentet er opbygget i fem hovedafsnit.\nNærværende afsnit 1 udgør en kort indledning.\nAfsnit 2 indeholder en redegørelse for de principper og forretningsbehov, der ligger til grund for de angivne retningslinjers udformning.\nAfsnit 3 indeholder angivelse af generelle retningslinjer, der skal anvendes 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.\nAfsnit 4 indeholder en angivelse af retningslinjer, der er specifikke for REST webservices.\nAfsnit 5 indeholder en referenceliste.\nAfsnit 6 indeholder et tværgående eksempel.\nDokumentet henviser til følgende bilag:\nBilag 1 ”Dokumentation for REST Webservices” Bilaget giver uddybende beskrivelse af retningslinje R06.\nBilag 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.\nBilag 3 ”Nonfunktionelle krav til realisering af retningslinjer” indeholder et kravbilag, som kan anvendes af serviceudbydere til at kravstille webservices, som overholder retningslinjerne.\nBilag 4 ”Specifikation for brug af HTTP til REST” uddyber mere detaljeret 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.\nDokumentet indeholder følgende retningslinjer opdateret efter tema.\nGenerelle retningslinjer for webservices\nFokus på serviceanvendere\nR01. Udstil minimal funktionalitet og data i den enkelte webservice\nR02. Separér webservices fra konkret implementering\nR03. Separér webservices fra eksterne afhængigheder\nAnsvarsfordeling ved kald til webservices\nR04. Understøt gentagne forsøg på kald fra serviceanvenderen\nR05. Kræv specifikkke informationer ved ansvarsoverdragelse ved kald til webservices\nR06. Dokumentér udstillede webservices i overensstemmelse med den fællesoffentlige dokumentationsramme for webservices\nR07. Opmærk webservices i henhold til fællesoffentlige emnesystematikker\nR08. Opmærk webservices med følsomhed eller fortrolighed af data\nR09. Dokumentér servicespecifikke fejlkoder for webservices\nR10. Dokumentér drift af forskellige versioner af webservices\nR11. Anvend semantisk versionering af webservices\nR12. Viderefør gamle versioner, når en webservice ændres\nR13. Log alle kald til webservices\nR14. Anvend transaktionsidentifikatorer ved kald og svar\nR15. Anvend requestID ved kald og svar\nR16. Understøt monitorering af udstillede webservices\nR17. Returnér servicespecifikke fejl som standardiserede fejlmeddelelser\nR18. Forretningsregler vedrørende temporaler indkapsles og håndhæves på serviceniveau\nR19. Webservices med temporale ressourcer returnerer som et øjebliksbillede\nR20. Webservices med temporale ressourcer anvender anerkendte nøgleord i søgeparametre.\nR21. Webservices med temporale ressourcer skal udstille ensartet funktionalitet til revision og Linje\nR22. Webservices med temporale ressourcer skal anvende ens håndtering af tidspunkter\nSikkerhedskrav til webservices\nR23. Webservices skal have tokenbaseret sikkerhed\nRetningslinjer for REST webservices\nModellering af REST webservices\nR24. Udstil webservices som REST ressourcer\nR25. Udstil data som REST ressourcer\nR26. Modellér REST ressourcer med udgangspunkt i forretningsmodellering\nR27. Navngiv REST ressourcer ud fra forretningsmodellens begreber\nR28. Navngiv REST ressourcer ud fra REST arkitekturstilen\nR29. Udstillede REST ressourcer har unikke, sikre identifikatorer\nR30. Udstil REST ressourcers relaterede entiteter\nR31. Returnér REST ressourcer med hypertext links\nSøgninger i REST webservices\nR32. Anvend standardiserede REST fremsøgningsparametre\nR33. Understøt søgning med delresultater\nDatarepræsentation i REST webservices\nR34. Repræsentér REST ressourcer i et standardiseret dataformat\nR35. Deklarér REST ressourcer datarepræsentationer\nR36. Overfør tekst i en internationaliseret repræsentation\nR37. Anvend HTTP som fællesoffentlig REST kommunikationsprotokol\nR38. Anvend HTTPs mekanismer til effektiv kommunikation\nR39. Anvend HTTP sikkert til REST ressourcer\nSikkerhedskrav til REST webservices\nR40. REST webservices skal anvende OIO IDWS REST profile V1.0\nRetningslinjerne beskrives efter følgende mønster:\nAngiver nummeret og navnet på retningslinjen\nBeskriver retningslinjen klart og præcist\nBeskriver forretningsværdien ved at følge retningslinjen\nBeskriver de konkrete forretningsbehov, som retningslinjen understøtter\nBeskriver hvilken indvirkning, retningslinjen har på forretningsmæssig og teknisk implementering\nFør beskrivelsen af hver retningslinje kan der være en kort indledning, der forklarer 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.\nPrincipper og forretningsbehov for retningslinjer\nRetningslinjerne for webservices er udarbejdet med henblik på at være bredt anvendelige i den offentlige sektor. Retningslinjerne er baseret på praktisk erfaring, samt målrettet anvendelse i realiseringen af Hvidbog om arkitektur for digitalisering. Anvendeligheden sikres ved specificering af tre overordnede principper samt en række forretningsbehov, som retningslinjerne udmønter. Principper og forretningsbehov i dette afsnit har således udgjort grundlaget for udarbejdelsen af retningslinjerne, der fremgår af afsnit 3 og 4.\nDen organisation, som ønsker at anvende retningslinjerne, bør undersøge, om organisationen har forretningsbehov, der adskiller sig væsentligt fra de her anførte forretningsbehov. Hvis dette er tilfældet, kan organisationen overveje, hvorvidt snitfladerne skal udarbejdes efter retningslinjerne. Tilsvarende kan det være nødvendigt, at den pågældende organisationen tager stilling til, hvilke forretningsbehov, der er vigtigst.\nFølgende tre principper gælder for alle retningslinjerne:\nRetningslinjerne skal kunne anvendes bredt af offentlige institutioner, samt andre organisationer der ønsker at anvende dem.\nRetningslinjerne skal baseres på viden fra anvendelser af eksisterende retningslinjer for webservices, bl.a. fra SKAT, Sundhedsdatastyrelsen, Grunddataprogrammet, KOMBIT m.fl.\nRetningslinjerne skal være langtidsholdbare, men samtidig være tilstrækkeligt konkrete og implementeringsnære til, at retningslinjerne kan inddrages af initiativerne i digitaliseringsstrategien.\nForretningsbehov er opdelt i tre overordnede temaer.\nTema 1: Forretningsbehov vedrørende serviceanvendere og serviceudbydere\nTemaet addresserer dilemmaet i at designe services, der er bedst for både serviceanvendere og serviceudbydere. Retningslinjerne sætter fokus på, at serviceudbydere prioriterer servicenanvendernes behov og har et udefra-og-ind perspektiv, når webservices skal designes. Dermed menes, at serviceudbyder forstår formålet med webservicen fra serviceanvenderens perspektiv.\nF1. Webservices skal være omkostningseffektive set i et fællesoffentligt perspektiv, således at der er fokus på totalomkostningen for serviceanvendere og serviceudbydere i webservicens levetid. Webservices skal kunne realiseres af serviceudbydere ved brug af eksisterende og velbeskrevne metoder samt udbredte værktøjer og rammeværk.\nF2. Design af webservices skal tage udgangspunkt i serviceanvenderens behov. Det vil sige, at webservices udstilling af data og funktionalitet er intuitiv og enkel at anvende for en serviceanvender.\nÆndringer i webservices skal udformes således, at det er så omkostningseffektivt som muligt for serviceanvendere.\nÆndring af udstillede webservices medfører nødvendige tilpasninger hos serviceanvendere. Ændringer hos serviceanvendere medfører ekstra omkostninger og kan give stærke bindinger i it-landskabet, ved at en serviceudbyder ikke kan ændre en webservice før væsentlige serviceanvendere, eller i værste tilfælde alle serviceanvendere, er klar til ændringen. Hvis antallet 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 webservices skal derfor have som mål at minimere konsekvenser for serviceanvendere ved ændringer i en webservice. Det vil være totaløkonomisk fordelagtigt at mindske bindingerne mellem serviceudbyder og serviceanvender, 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.\nF4. Webservices skal have en entydig mekanisme til ansvarsoverdragelse mellem 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 meddelelser til Digital Post.\nF5. 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.\nTema 2: Forretningsbehov vedrørende data og funktionalitet\nTemaet fokuserer på behovene for, at udstilling af data via webservices sker på en måde, som sikrer mest mulig interoperabilitet.\nF6. REST webservices skal udstille forretningsobjekter som ressourcer på en ensartet måde for at sikre interoperabilitet, jf. afsnit 2.1.\nF7. 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.\nF8. REST webservices skal anvende relevante eksisterende og kommende fællesoffentlige datastandarder og profiler for REST ved udvikling af nye versioner af en REST webservice.\nF9. Webservices skal udstille data i bredt anvendte dataformater.\nF10. Webservices skal tage højde for, at data kan have forskellige grader af fortrolighed, hvilket stiller forskellige krav1 til egenskaberne ved en webservice. Fx kan en webservice udstille personoplysninger.\nTema 3: Forretningsbehov vedrørende stabil og sikker driftsafvikling\nTemaet omhandler behovene for, at webservices kan indgå i et fællesoffentligt itlandskab på en forvaltningsmæssig sikker og effektiv måde.\nF11. Serviceudbydere skal kunne dokumentere anvendelsen af data og funktionalitet i webservices, herunder webservicens håndterinng af svartider og fejlsituationer.\nF12. 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.\nF13. Webservices skal kunne udstille adgang til data og funktionalitet af fortrolig eller følsom karakter. Når serviceudbyderen anvender (f.eks. danske udgaver af) udbredte, gældende sikkerhedsstandarder i stedet for at definere egne sikkerhedsmodeller, vil kravene til databeskyttelse med højere sandsynlighed være opfyldt.\nDette afsnit indeholder retningslinjer, der understøtter forretningsbehovene beskrevet 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.\nEn 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 serviceanvendere i orkestrering og viden om sammenhænge mellem services.\nEn webservice, som udstiller generiske operationer2, kan anvendes af mange serviceanvendere med forskellige behov. En generisk webservice får derfor mange 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 serviceanvendere. 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.\nWebservices skal designes således, at én webservice kun udstiller tilstrækkelig data eller funktionalitet for at give forretningsmæssig mening for en bestemt serviceanvendelse.\nEn ændring til data og funktionalitet skal som udgangspunkt kun medføre ændringer i den webservice, der udstiller funktionaliteten. På denne måde minimeres behovet for ændringer i etablerede serviceanvenderes klienter. Serviceanvenderes klienter skal kun ændres, hvis ændringen påvirker deres serviceanvendelse.\nRetningslinjen understøtter forretningsbehov F2 og F3, idet den medfører, at serviceanvendere samlet set påvirkes mindre.\nEn webservice løser ideelt set kun én opgave3, hvilket har den konsekvens, at genbrugeligheden af den enkelte webservice bliver reduceret. Til gengæld vil det samlede økosystem være bedre i stand til at håndtere ændringer, da det kun vil være serviceanvendere, som har behov for en ændring, som påvirkes.\nEt eksempel er en søgefunktionalitet, som udstilles til mobile klienter og rige klienter. Her vil en anvendelse af et backend 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 mobile 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ødelokale og tilhørende bookinger. Funktionen ”Ret mødelokale” skal således understøtte redigering af mødelokalets attributter, men også tilhørende bookinger. Det medfører, at samtlige serviceanvendere skal anvende ”Ret mødelokale”, selvom serviceanvendere har forskellige serviceanvendelser, hvor én kun retter mødelokalets data, og en anden kun opretter bookinger.\nEt andet eksempel kunne være ved tilføjelse af et nyt obligatorisk attribut på mødelokale, så vil det være en breaking change for alle serviceanvendere.\nEn 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 anvender funktionen ”opret booking”.\nWebservices skal designes, så de afkobler implementeringen af interne og eksterne forretningsobjekter fra den snitflade, der udstilles imod serviceanvendere.\nVed 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.\nRetningslinjen er affødt af forretningsbehov F3 ved at afskærme serviceanvenderen fra udbyderens interne, flygtige og evt. irrelevante anvendelse af data og funktionalitet\nVed 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 repræsentation, der ikke fastholder serviceudbyderen i den samme konkrete implementering af webservicen i hele servicens levetid.\nWebservices skal designes, så snitfladen udstiller egne datasæt og ikke har eksterne afhængigheder til andre domæners objekter.\nNår webservicen udstiller en facade foran den bagvedliggende forretning, får serviceanvenderen kun det nødvendige data, for at reducere kompleksitet og gardere mod konsekvenser af ændringer fra bagvedliggende systemer.Forretningsmæssige webservices, der udstiller data, kan være en aggregering af data fra andre webservices. Webservicen 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 bagvedliggende webservices ikke påvirke serviceanvendere, medmindre facaden ændres.\nRetningslinjen er affødt af forretningsbehov F3 ved at afskærme serviceanvenderen fra fremmede forretningsobjekter.\nVed 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 ændringer i bagvedliggende webservices, da facaden skal opdateres.\nVed integrationer mellem forskellige myndigheders it-systemer er det centralt, at ansvaret for gennemførsel og fejlhåndtering ved en transaktion er tydeligt placeret. 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 forbindelse med overførsel af en administrativ opgave i forbindelse med en partens flytning af bopælsadresse.\nÆndring af data skal gennemføres entydigt. Serviceudbyderen skal derfor håndtere, 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”.\nEn webservice skal entydigt kunne håndtere gentagne forsøg fra serviceanvenderen.\nEn 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 serviceanvenderen, der kan afgøre, om svaret på et kald er modtaget.\nRetningslinjen er affødt af forretningsbehov F4.\nDet 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.\nHvis 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”.\nWebservices kræver, at en serviceanvender medsender en transaktionsidentifikator ved alle kald, jf. retningslinje R14, derfor kan transaktionsidentifikatoren anvendes af serviceudstiller til at detektere gentagne forsøg, og håndtere gentagelsen korrekt.\nR05. Kræv specifikke informationer ved ansvarsoverdragelse ved kald til webservices\nWebservices, der understøtter overdragelse af myndighedsansvar, skal kræve, at specifikke overdragelsesinformationer inkluderes i kaldet og skal eksplicit returnere en kvittering for, at overdragelsen er accepteret.\nDet 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 informationer om overdragelse af ansvar i kaldet. Den valgte kommunikationsprotokols (fx HTTP) tekniske kvitteringer kan ikke nødvendigvis erstatte forretningsmæssige kvitteringer for ansvarsoverdragelse. Fx kan en snitflade måske ikke synkront opdatere de bagvedliggende forretningssystemer. Dermed kan serviceudbyder ikke give en forretningsmæssig kvittering, før alle bagvedliggende systemer er opdateret korrekt.\nServiceudbyderen skal designe webservicen således, at eksplicitte overdragelsesinformationer skal være til stede i et korrekt kald til webservicen. Disse informationer kan fx omfatte:\nIdentifikation af den ansvarsafgivende organisation/myndighed.\nIdentifikation af den ansvarsmodtagende organisation/myndighed.\nEn unik identifikator af denne ansvarsoverdragelse.\nEn identifikation af hvilket ansvar, der overdrages, f.eks. ved reference til en aftalt klassifikation, emnesystematik eller lovgrundlag.\nServiceudbyderen skal realisere webservicen, så den returnerer et kvitteringssvar, der indikerer, at ansvaret er overdraget.\nSåfremt en REST webservice opdaterer det bagvedligggende forretningsystem asynkront for at kunne overdrage ansvar, så skal forretningskvitteringen følge mønsteret beskrevet i Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices”.\nServiceudbydere skal dokumentere alle udstillede webservices. Dokumentationen skal målrettes serviceanvenderens behov for information, både forretningsmæssigt 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.\nServiceanvenderes 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 serviceanvenderen tilstrækkelig viden.\nDokumentationen for webservices skal følge den fællesoffentlige dokumentationsramme, der udgøres af Bilag 1 ”Dokumentation for REST Webservices”.\nGod dokumentation er opdelt og opmærket på en måde, der gør, at dokumentationens enkeltdele målrettes de forskellige roller hos serviceanvenderen (f.eks. forretningsansvarlig eller it-arkitekt). Det er en nødvendig forudsætning, at den udstillede dokumentation altid er ajourført, så dokumentationen svarer til den udstillede webservice.\nAlle webservices skal være dokumenterede i overensstemmelse med den fællesoffentlige dokumentationsramme, og dokumentationen skal være let tilgængelig, ajourført og svare til de udstillede webservices.\nDokumentationen muliggør, at serviceanvendere forstår, hvordan udstillede webservices anvendes uden at skulle konsultere eller kontakte serviceudbyderen. Ved fx at synliggøre semantik og syntaks sikres synlighed og ensartethed, så webservicedata og funktionalitet har samme betydning for både serviceudbyder og serviceanvender.\nServiceudbyderen mindsker ressourceforbruget i sin support, når let tilgængelig dokumentation medfører, at serviceanvenderen kan finde de relevante dele af dokumentationen.\nRetningslinjen er affødt af forretningsbehov F2.\nKrav til dokumentationen fremgår af den fællesoffentlige dokumentationsramme for webservices, som er beskrevet i Bilag 1 ”Dokumentation for REST Webservices”.\nDokumentation af webservices skal overholde de krav, som er angivet i Bilag 1 afsnit 2 og skal stille tilsvarende dokumentation til rådighed, jf. Bilag 1 afsnit 3.\nFor REST webservices gælder det, at serviceudstiller skal anvende OpenAPI med SmartAPI udvidelser. Ved alle ændringer til webservicen skal dokumentationen opdateres, senest når ændringen idriftsættes, således at en webservice altid er udstillet med opdateret dokumentation.\nServiceudbyderen skal opmærke udstillede webservices i henhold til fællesoffentlige emnesystematikker.\nServiceudbyderen 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 relation til. Som en del af den forretningsrelaterede del af dokumentation for webservices skal serviceanvenderen bibringes viden om, hvilken offentlig forvaltning, forvaltningsprocesser eller andre processer, webservicen er en del af hos serviceudbyderen.\nDokumentationen af den enkelte webservice skal inkludere opmærkning i henhold til fællesoffentlige emnesystematikker, dvs. enten KLE, FORM eller anden relevant, anerkendt fællesoffentlig emnesystematik.\nOpmærkningen beskrives for den enkelte webservice. Hvis en webservice indgår i flere forvaltningsprocesser eller forvaltningsemner, skal alle emnerne angives i dokumentationen.\nOpmærkningen for REST webservices skal foretages som angivet i Bilag 1 ”Dokumentation for REST Webservices”.\nServiceudbyderen skal i dokumentationen opmærke udstillede webservices med en angivelse af følsomhed/fortrolighed af data, der skal angives enten ved kald eller returneres ved svar.\nServiceudbyderen angiver følsomhed for de data, der overfø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 tydeligt overfor serviceanvenderen, hvordan data til og fra webservicen skal behandles.\nOpmærkningen angives ikke i selve kaldet eller svaret, men som en del af webservicens dokumentation. Dokumentationen af den enkelte webservice skal inkludere opmærkning i henhold til klassificering af følsomhed og fortrolighed i den fællesoffentlige dokumentationsramme for webservices.\nOpmæ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 dokumentationsramme.\nEn REST webservice skal opmærke følsomhed og fortrolighed i OpenAPI, jf. Bilag 1 ”Dokumentation for REST Webservices” afsnit 3.2.9.\nHvis en webservice har data med flere niveauer, angives det højeste niveau af følsomhed eller fortrolighed, jf. klassifikation af niveauer i den fællesoffentlige dokumentationsramme.\nServiceanvenderen har behov for at kende til de servicespecifikke fejl, en webservice kan returnere som svar på kald til webservicen. Servicespecifikke fejl er fejl, der opstår i udveksling mellem service og serviceanvender. Fx hvis serviceanvenderen 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.\nAlle servicespecifikke fejl, der kan returneres fra en webservice, skal dokumenteres, og dokumentationen skal indgå i webservicens dokumentation og gøres tilgængelig for serviceanvendere.\nServiceanvendere skal kunne forstå, hvorfor kald til en udstillet webservice ikke kan gennemføres, så serviceanvenderen eventuelt kan kompensere for problemet. Hvis servicespecifikke fejl dokumenteres, får serviceanvenderen mulighed for selv at løse problemerne i stedet for at skulle bebyrde serviceudbyderen med bistand til at løse problemet.\nDokumentationen for webservices skal inkludere en oversigt over alle servicespecifikke fejl, samt dokumentation af hver enkelt servicespecifik fejl.\nDokumentationen af den enkelte servicespecifikke fejl bør angive, hvilken fejlkode (en værdi) fejlen er identificeret ved, en fejlbeskrivelse og årsag.\nDokumentationen af servicespecifikke fejl er en del af webservicens dokumentation og skal udstilles til serviceanvendere. Fejlhåndtering for serviceudbyder omfatter ikke fejl i infrastrukturen mellem serviceanvender og webservice.\nFejlbeskrivelser 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 fejlstrukturen beskrevet i bilag 4.\nServiceudbydere vil øge interoperabiliteten ved at tydeliggøre ændringer til webservices, så serviceanvendere kan afgøre, om ændringens effekt fordrer konsekvensændringer hos dem selv.\nServiceudbyderen skal dokumentere vilkårene i forbindelse med samtidig driftsafvikling af versioner af den samme webservice.\nServiceanvendere kan få fordel af at være tydeligt informerede 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 ikkekompatibel ændring af denne, jf. retningslinje R11 om versionering).\nServiceudbyderen skal fastlægge og dokumentere sin release- og versioneringsstrategi for den enkelte webservice, jf. retningslinje R11, og publicere denne sammen med dokumentationen for udstillede webservices. Serviceudbydere skal dokumentere deres strategi for, i hvilket omfang forskellige versioner af en udstillet webservice driftsafvikles samtidigt. Serviceanvendere får dermed en forståelse for, hvor hurtigt de skal tilpasse sig ved ændringer til webservice.\nDet bør fremgå af dokumentationen:\nHvordan webservices versioneres i henhold til R11.\nHvor længe gensidigt inkompatible webservices udstilles i flere udgaver, samt antallet heraf.\nOm, og i givet fald hvor længe i forvejen, serviceudbyderen adviserer serviceanvendere om ændringer.\nHvordan serviceanvendere eventuelt kan identficere sig over for serviceudbyder.\nHvordan serviceudbyderen udstiller en oversigt over konkrete datoer for publicering af nye webservices samt ændringer til og nedlæggelse af eksisterende webservices.\nDet 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.\nNår ændringer er nødvendige, skal webservicens version tydeligt indikere over for serviceanvenderen, om webservicen er kompatibel med den tidligere udgave.\nVed 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 serviceanvenderen.\nVersionering af udstillede webservices er via mekanismen ”semantisk versionering”4 et middel til at gøre det klart, tydeligt og entydigt over for serviceanvendere, 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 versionsnumre er således:\nTo 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 version 2.0 af webservicen.\nNår to versioner af en webservice har samme major version men forskellige 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 mulighed for at anvende mere funktionaltiet i den nye version.\nHvis to versioner af en webservice har samme major og minor version men forskellig 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 ændre en ressources URI, som er den unikke sti til en given ændring, fx ændring af serverens DNS navn i en HTTP URI for en REST ressource – dette opfattes derfor som en ikke-kompatibel ændring.\nWebservices skal anvende semantisk versionering til at tydeliggøre kompatibilitet og overholde versioneringsreglerne.\nServiceanvendere 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 komponenter i et versionsnummer, der gør dette klart: ændringer i ”major” komponenten i servicens versionsnummer betyder brud på kompatibilitet med eksisterende serviceanvendelser.\nRetningslinjen er affødt af forretningsbehov F2 og F3.\nWebservices skal garantere kompatibilitet mellem versioner af en webservice ifølge reglerne for semantisk versionering. Webservices kan eventuelt understøtte, at serviceanvenderen kan specificere den ønskede version af webservicen i forbindelse med et kald.\nEn konsekvens af denne versionering er, at følgende ændringer generelt medfører en ny major version:\nEn valgfri kaldsparameter bliver obligatorisk.\nTilføjelse af en ny obligatorisk parameter ved kald.\nFjernelse af værdier i svar.\nSemantiske ændringer af data i kald eller svar\nAndre ændringer, som fx ændring af sikkerhedsmodel og sletning af udstillede attributter eller relationer, er normalt en ikke-kompatibel ændring. Andre ikke-kompatible ændringer, der kræver nyt versionsnummer, er f.eks. introduktion af nye obligatoriske parametre eller begrænsning i mængden af mulige parametre.\nServiceudbyderen skal videreføre versioner i en tilstrækkelig overgangsperiode.\nNår der sker ikke-kompatible ændringer til udstillede webservices 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.\nEksisterende serviceanvendere vil kun undtagelsesvist skulle tilpasse sig til brug af en ændret webservice. Serviceudbyderen må derfor antage, at serviceanvendere har behov for en overgangsperiode, hvor både gammel og ny udgave af webservicen udstilles samtidigt.\nHvis ændringen udgør en breaking change, skal serviceudbyderen udstille både ny og gammel version af webservicen i en overgangsperiode. Serviceudbyderen skal dokumentere dette, jf. retningslinje R10.\nLogning og juridiske krav til logning er ikke færdig analyseret i version 0.9, dette afsnit er derfor ikke endeligt.\nI forbindelse med integration mellem it-løsninger er det nødvendigt, på forlangende, at kunne redegøre for afviklingen af et kald og svar herpå. Typiske fejlsituationer 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.\nAlle væsentlige kald til og svar fra webservices skal logges af serviceudbyderen.\nDet skal sikres, at alle væsentlige kald til en webservice logges. 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 sletning af persondata kan opfyldes.\nRetningslinjen er affødt af forretningsbehov F2, F12 og F11.\nServiceudbyder skal logge alle kald til en given webservice, hvor følsomme eller fortrolige informationer behandles i henhold til relevant lovgivning. Serviceudbyder skal desuden 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ødvendigt, at både serviceanvender og serviceudbyder foretager logning.\nServiceudbyderen skal dokumentere, hvilke kald en given webservice logger.\nWebservicen skal desuden foretage logning af alle eksterne kald, der foretages som konsekvens af det modtagne kald, hvor fortrolige eller følsomme data er involverede.\nFor at sikre at logningen hos serviceanvender og serviceudbyder kan sammenholdes, skal det enkelte kald være unikt identificeret. En sådan identificering har form af en unik transaktionsidentifikator.\nWebservices 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\nDet skal være muligt for serviceanvendere og serviceudbydere at spore sammenhængen i servicekald på tværs.\nRetningslinjen er affødt af forretningsbehov F1, F12 og F11.\nServiceudbyderen skal kræve, at serviceanvenderen medsender en globalt/universelt unik transaktionsidentifikator for hvert kald til en udstillet webservice.\nTransaktionsidentifikatoren kan f.eks. være et UUID, jf. ietf RFC 4122.\nWebservicens svar skal inkludere transaktionsidentifikatoren fra kaldet.\nWebservices sender transkationsidentifikatoren med videre, hvis forespørgslen giver anledning til kald videre til andre webservices.\nWebservices skal logge et unikt requestID ved hvert kald, og ved gensendelse af et svar skal samme RequestID anvendes.\nEntydighed af det enkelte kald giver mulighed for sporing på tværs af services.\nDet skal være muligt for serviceanvendere og serviceudbydere at spore individuelle kald. Ved at inkludere en reguestID i kald og svar, vil det være muligt for både serviceanvender og serviceudbyder at identificere et bestemt kald.\nServiceudbyderen skal medsende en unik requestID for hvert kald til en udstillet webservice.\nRequestID kan f.eks. være et universelt unikt id, jf. internet RFC 4122.\nMonitorering 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. Serviceanvendere kan anvende informationen til at afgøre, om en udstillet webservice er tilgængelig på et givet tidspunkt.\nUdstillede webservices skal understøtte, at serviceanvenderen kan monitorere webservicens tilgængelighed.\nServiceanvendere 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 robusthed end de webservices, der anvendes til forretningsprocesserne.\nUdstillede webservices skal udstille en snitflade, som viser, om en webservice er tilgængelig eller ikke. Monitoreringen kan enten være inkluderet som en dedikeret\n(del)funktionalitet af en udstillet webservice eller være udstillet som en sideordnet webservice.\nUdstillede webservices kan eventuelt udstille specifik funktionalitet til visning af tilgængeligheden af webservicens og at ressourcer, som webservicen er afhængig af, er tilgængelige. En sådan funktionalitet har typisk ingen parametre og kræver ingen sikkerhedsmæssige rettigheder hos serviceanvenderen. Alternativt kan monitorering understøttes ved at dokumentere en særlig måde at anvende en udstillet webservice på. Dette kunne fx være et fremsøgningskald, der aldrig returnerer data, men svarer med 0 fundne forretningsobjekter, og hvor brugen heraf til monitorering er dokumenteret af serviceudbyderen.\nDet er centralt, at monitoreringen ikke foretager opdateringer i data. Logning hos serviceudbyderen er i denne forbindelse 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.\nNå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 Webservices”.\nWebservices skal returnere servicespecifikke fejl som standardiserede fejlmeddelelser til serviceanvenderen med dokumenterede fejlkoder som beskrevet i Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices”.\nDokumentationen af fejlmeddelelser skal angive over for serviceanvenderen, om kaldet er idempotent. Serviceudbyderen bør dog kun angive, at et gentaget kald er en fejl, når serviceudbyderen med sikkerhed ved, at gentagelse vil resultere i samme fejl.\nFor det første er det vigtigt, at alle fejl forsynes med en dokumenteret fejlkode (en entydig værdi, f.eks. et tal) og et fejlnavn (en overskrift), så serviceanvenderen kan finde fejlen i servicens dokumentation.\nFor det andet er det vigtigt, at alle fejlmeddelelser indeholder identifikation af, hvor fejlen er opstået, hvilket både kan være hos serviceudbyderen eller hos et system, der kaldes af serviceudbyderen.\nMeget store fejlmeddelelser skal dog undgås grundet båndbreddeforbrug. Desuden må fejlmeddelelsen ikke indeholde data, som påvirker sikkerhedskrav og krav om informationers følsomhed og fortrolighed.\nWebservices skal derfor anvende den fællesoffentlige struktur for fejlmeddelelser for webservices. Strukturen beskrives i Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices”. REST webservices skal endvidere anvende de statuskoder 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 kunne udføre fejlhåndtering. Data eller opdateringer af data kan dermed gå tabt.\nRetningslinjen er affødt af forretningsbehov F2, F6 og F12. Retningslinjen præciserer OIO serviceprincippet ”Services returnerer sigende fejlmeddelelser”, jf. [OIOSVC].\nFejlmeddelelser vedrørende servicespecifikke fejl returneres i den fællesoffentlige struktur for fejlmeddelelser, jf. Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices”.\nFejlmeddelelser skal anvendes i kontekst af den valgte transportprotokol, der også returnerer fejlkoder. For REST webservices gælder retningslinje R37. Det betyder, at transportprotokollens fejlkoder skal bruges korrekt, når servicespecifikke fejl returneres i svar.\nDer kan være behov for at angive forskellige tidsmæssige aspekter af en ressource – såkaldte temporaler – i en webservice. Dette afsnit indeholder retningslinjer for ensartet udstilling af temporaler, hvor en serviceudbyder finder dette nødvendigt. 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.\nEt 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.\nDer er også andre dimensioner af temporaler, hvor man kan angive gyldighedsperioder 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\nUdstillet data, som indeholder mere end en enkelt temporal dimension, betegnes som en multi-temporal model. Typisk begrænser dette sig i praksis til to temporale dimensioner og benævnes ’bitemporalitet’. Bitemporale ressourcer er karakteriseret 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).\nFx 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.\nDette 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 ressourcen til at gælde for periode 2 [g1;g2] til registreringstidspunktet r1. Og endeligt opdateres ressourcen til at gælde for periode 3 [g0;g2] til registreringstidspunktet r2. Figuren nedenfor illustrerer, hvorledes den bitemporale plan for eksemplet ser ud.\nFigur 1 Illustrativt eksempel på registreringhistorik og gyldighedsperioder med tre registreringer\nBitemporale ressourcer anvendes til at understøtte en lang række særskilte forretningsbehov afhængigt af det enkelte domæne:\nBehov for at kunne registrere gyldighed for en ressource for og/eller bagud i tid.\nBehov for at kunne fremsøge ressourcens tilstand til et givent gyldighedstidspunkt og registreringstidspunkt er ”nu”- også kaldet et Punkt eller et øjebliksbillede.\nBehov for at kunne fremsøge ressourcens gyldige tilstande over en periode - også kaldet en Linje.\nBehov for at kunne se registreringsperioden for en gyldighedstidsperiode - også kaldet en Flade.\nFigur 2 Søgemuligheder ved bitemporalitet\nFor at imødekomme disse fire generelle behov opstilles følgende retningslinjer:\nWebservices, som udstiller temporale data, skal garantere datas integritet i samtlige temporale dimensioner.\nServiceudbyderen skal sikre, at den udstillede service validerer input fra opdaterende servieoperationer, således at ressourcens integritet bevares gennem hele ressourcens levetid.\nRetningslinjen understøtter forretningsbehov F2 og F3, idet den sikrer høj datakvalitet for serviceanvendere.\nEn webservice skal designes således, at ressourcens integritet bevares. Særligt gælder det at Ressourcer, som indeholder referencer til andre ressourcer med eget gyldighedsområ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 dedikerede ressourcer, som opretter og vedligeholder udstillede data.\nSom udgangspunkt skal en temporal ressource kunne tilgås så enkelt som overhovedet muligt for en serviceanvender. Derfor er der behov for en ensartet, forenklet udstilling af temporale ressourcer.\nWebservices, som udstiller bitemporale ressourcer, skal returnere det øjebliksbillede for registring og gyldighed, som er gældende for fremsøgningstidspunktet, medmindre andet angives af serviceanvender.\nSelvom det er muligt at angive andre intervaller i et temporale, så er det typiske scenarie – også for temporale ressourcer - 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 øjebliksbillede af den temporale ressource.\nRetningslinjen understøtter forretningsbehov F2 og F3, idet den sikrer, at servicesanvendelsen forenkles for serviceanvendere.\nWebservices, 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 forretningsbehov.\nWebservices kan således kun udstille temporaler for et givent gyldighedstidspunkt og registeringstidpunkt (et punkt), mens returnering af flader og linjer af gyldighed kun kan returneres i dedikerede funktioner.\nFor at sikre genkendelighed på tværs af services, som udstiller temporale ressourcer, er det vigtigt, at gyldighedsperioder og registeringsperioder i søgeparametre udtrykkes ensartet.\nWebservices, som udstiller funktionalitet, der indeholder temporale ressourcer, skal anvende søgeparameteren ”GyldigTidspunkt”, som angiver tidspunkt for gyldighed som ønskes vist, i det tilfælde at servicen har bitemporalitet.\nRegistreringstidspunkt er altid webservicens tidspunktet for modtagelse af kaldet og skal ikke udstilles som parameter.\nDer anvendes anerkendte nøgleord som temporale søgeparametre for at gøre det genkendeligt over for serviceanvendere, hvorledes en webservice, som udstiller temporale ressourcer, kan kaldes. Temporalitet øger dog kompleksiteten af webservicen både i parametre og det resulterende datasæt, og derfor skal funktionalitet som standard kun understøtte øjebliksbilleder.\nWebservices, som håndterer bitemporale ressourcer, skal designes således, at søgeparametre, som vedrører en ressources temporaler, anvender anerkendte nøgleord.\nWebservices, som ønsker at udstille flader og linje for temporale 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ølgende nøgleord som søgeparametre:\n”GyldigFra”, der angiver starttidspunkt for gyldighed.\n”GyldigTil”, der angiver sluttidspunkt for gyldighed.\n”RegistreringFra”, der angiver starttidspunkt i et interval i en flade.\n”RegistreringTil”, der angiver sluttidspunkt i et interval i en flade.\nDa bitemporal logik kan være vanskelig at kommunikere og forstå, er det vigtigt, at servicen designes således, at det er 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.\nEt 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.\nDette skal afspejles i designet af webservicen.\nRetningslinjen understøtter forretningsbehov F2 og F3, idet den sikrer, at serviceanvendelsen forenkles for serviceanvendere.\nWebservices, som udstiller temporale ressourcer, skal designes således at, såfremt der er behov for udstilling af en flade, 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).\nGyldigFra er altid inkluderet i resultatet.\nGyldigTil er altid ekskluderet i resultatet.\nRegistreringFra er altid inkluderet i resultatet.\nRegistreringTil er altid ekskluderet i resultatet.\nHåndtering af angivne tidspunkter skal være ens for at understøtte interoperabilitet.\nWebservices, som udstiller temporale ressourcer, skal designes således, at serviceanvenders håndtering af tidspunkter i registrering og gyldighed altid håndteres ens.\nWebservices skal kunne udveksle data sikkert og effektivt på tværs af myndigheder ved anvendelse af SAML 2.0 og Transport layer security.\nWebservices skal anvende tokenbaseret sikkerhed\nFø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 administrativt.\nRetningslinjen understøtter forretningsbehov F13 og F2.\nUdveksling af data med webservices mellem offentlige institutioner skal således anvende tokens og kan ikke opsættes som punkt til punkt forbindelser. Dog kan certifikater anvendes til TLS.\nRetningslinjer for REST webservices er opdelt i følgende områder:\nModellering af REST webservices.\nSøgning i REST webservices.\nDatarepræsentation i REST webservices.\nREST webservice specifikation.\nSikkerhedskrav til REST webservices.\nServiceanvendere har typisk behov for anvendelse af udstillede webservices i forbindelse med gennemførsel af en forretningsproces i organisationen. Forretningsprocesser vil løbende ændre sig, fx på baggrund af ændrede forretningsbehov, ændret lovgivning, øget eller ændret digitalisering eller modernisering af itløsningerne. De involverede webservices ændrer sig i takt med ændringerne til forretningsprocesserne.\nEn REST webservice udstiller en ressource. En ressource er i princippet en betegnelse 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.\nREST webservices skal udstille data som ressourcer, der kan læses og evt. oprettes, opdateres og slettes, jf. [REST].\nREST 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ældende webservice ikke en REST webservice, men en anden type.\nRetningslinjen er affødt af forretningsbehov F6.\nRetningslinjen præciserer serviceprincipperne ”Services kan anvendes uafhængigt af platform” og ”Services kan anvendes uafhængigt af lokation”, jf. [OIOSVC].\nDe 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 informationer opfattes i denne sammenhæng som ”kontrakten”, uanset at der ikke foreligger en formel specifikation som i forbindelse med SOAP webservices. Informationerne kan inkludere krav til sikkerhedsmodel, datarepræsentation, m.m.\nI stedet for at udstille funktionalitet for forretningsoperationer på en webservice, er det selve objekterne, der udstilles som en web ressource og hentes via verber.\nEn ressource skal altid identificeres af en URI.\nDe URI’er, der eksplicit udstilles til omverdenen, vil serviceanvendere forlade sig på. URI’er for ressourcer vil blive opfattet af serviceanvendere som en aftale mellem serviceudbyder og serviceanvender. URI’er for eksplicit udstillede ressourcer kan derfor kun ændres i meget begrænset omfang, jf. afsnit 3.4.\nOperationer på ressourcen er givet ved valget af kommunikationsprotokol til REST, se retningslinje R37. For HTTPs vedkommende er dette HTTP operationerne GET, HEAD, PUT, POST, PATCH, DELETE og OPTIONS.\nI nogle situationer er det ikke data eller entiteter, der udstilles til en serviceanvender, 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 udstille en ressource, der f.eks. repræsenterer de data, der igangsætter forretningsprocessen. I det konkrete eksempel med udsendelse af breve kunne serviceudbyder udstille en service, der opretter en ny forsendelse.\nREST webservices udstiller data som ressourcer, der kan læses og evt. oprettes, opdateres og slettes i overensstemmelse med REST arkitekturstilen.\nREST 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 forretningsprocessen, og udstiller dem som en ressource.\nRetningslinjen præciserer serviceprincipperne ”Services kan anvendes uafhængigt af platform” og ”Services kan anvendes uafhængigt af lokation” (se [OIOSVC]).\nOperationer på ressourcen er givet ved valget af kommunikationsprotokol til REST, se retningslinje R37. Konkret betyder det f.eks. for HTTPs vedkommende, at HTTP operationerne PUT, GET og DELETE f.eks. kan anvendes til at igangsætte en forretningsproces, hente status, eller standse forretningsprocessen.\nREST ressourcer skal struktureres med udgangspunkt i den forretningsmodellering, der er udført efter de fællesoffentlige regler for begrebs- og datamodellering [MODEL].\nUdstillede 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 udstillede ressourcer. Forretningsmodelleringen bør være udført efter de fællesoffentlige regler for begrebs- og datamodellering, jf. [MODEL]. Hvor dette ikke er tilfældet, kan udgangspunktet være en tilsvarende model for domænet.\nModellering af ressourcer efter [MODEL] sikrer ensartet sprogbrug og fælles grundlag for at fastlægge granularitet og serviceboundaries. Det letter og tydeliggør den menneskelige forståelse af funktionalitet, syntaks og semantik for en webservice, hvis webservicens design har udgangspunkt i en modellering af forretningen. Samme forståelse af informationen sikres hos serviceanvender og serviceudbyder, og dermed etableres semantisk interoperabilitet.\nRetningslinjen omfatter og udvider OIO serviceprincippet ”Services understøtter forretningen”, jf. [OIOSVC].\nUdstillede ressourcer skal have oprindelse i en modellering af forretningens begreber og informationer.\nUdgangspunktet for ressourcerne skal være forretningsmodelleringens ”forretningsobjekter” med egenskaber. Relaterede entiteter udstilles i udgangspunktet som separate entiteter, jf. retningslinje R30.\nForretningsmodellering kan være en konsekvens af domænerelateret standardisering, f.eks. HL7/FHIR på sundhedsområdet.\nDer henvises til retningslinje R34 vedrørende repræsentation af ressourcers data.\nNavngivning af REST ressourcer skal tage udgangspunkt i den forretningsmodellering, der er udført efter de fællesoffentlige regler for begrebs- og datamodellering [MODEL].\nEt udgangspunkt i forretningsmodellens begreber sikrer ensartet navngivning og fælles grundlag for genbrug og fremsøgning. Forretningsmodelleringen afdækker forretningsobjekter 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.\nRetningslinjen er affødt af forretningsbehov F1 og F6.\nRessourcer navngives fra domænets begreber, f.eks. ”sager”, ”journalnotater”, ”parter”. Betegnelserne kan være en konsekvens af domænerelateret standardisering, f.eks.\nHL7/FHIR på sundhedsområdet. Se også retningslinje R28 vedrørende konkret navngivning.\nEn 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”.\nI REST arkitekturstilen angives ressourcen som et navneord, f.eks. ”/sager” eller ”/personer”, og et ”scheme”. Her vil en typisk protokol og placeringen af ressourcen angives foran ressourcens navn, f.eks. https://it.system.dk/sager.\nREST ressourcer skal navngives som navneord, jf. REST arkitekturstilen, og skal navngives tilsvarende serviceudstillers forretningsbegreber.\nFor at følge REST arkitekturstilen skal URI’er bestå af navne på ressourcer frem for navne på operationer eller funktionalitet. Konkrete instanser af ressourcer kan yderligere specificeres som f.eks. ”https://it.system.dk/lokaler/123” eller ”https://it.system.dk/personer/345”.\nRetningslinjen er affødt af forretningsbehov F6, F1 og F8.\nI 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”.\nAlle udstillede REST ressourcer skal have unikke identifikatorer (URI’er), der er stabile og sikre.\nREST ressourcers identifikatorer er et væsentligt element i den ”kontrakt”, en REST webservice udstiller. Hvis identifikatoren på en ressource ændres, vil serviceanvenderen ikke længere kunne finde den pågældende ressource. Det er derfor 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 serviceanvenderen. Det er vigtigt, at ressourcers identifikatorer ikke indeholder følsomme eller fortrolige informationer, eller sikkerhedsrelaterede 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.\nStabile identifikatorer sikrer, at data kan genfindes i ressourcernes levetid.\nREST ressourcers unikke identifikatorer skal være unikke, hvilket betyder, at de kun må udpege én ressource.\nDet skal være muligt for serviceanvendere at opbevare udstillede ressourcers identifikatorer.\nIdentifikatorerne 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.\nRetningslinjen er affødt af forretningsbehov F6 og F1.\nServiceudbyderen er selv ansvarlig for at definere identifikatoren 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 identifikatorer, 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 regler om sletning, der vanskeligt kan håndhæves.\nREST ressourcer skal udstilles sine entiteter ved at følge de fællesoffentlige regler for begrebs- og datamodellering [MODEL].\nRelationer til entiteter som udstilles af andre webservices skal udstilles ved at følge de fællesoffentlige regler for begrebs- og datamodellering [MODEL].\nEntiteter, der udstilles som REST ressourcer, vil ofte have relationer til andre entiteter.\nRelaterede entiteter bør udstilles som separate (under)ressourcer, som kan tilgås direkte ved brug af en passende identifikator (URI). Serviceanvendere gives dermed mulighed for at tilføje, ændre eller fjerne relaterede entiteter uden at skulle opdatere hele ressourcen.\nREST ressourcer repræsenterer begreber i forretningsmodelleringen. Forretningsmodelleringen afdækker relationer mellem entiteter. Disse relationer bør kunne tilgås som underressourcer, jf. REST arkitekturstilen, og gøre det forståelsesmæssigt lettere og teknisk mere effektivt at anvende webservicen.\nREST webservices bør udstille relaterede forretningsobjekter som underressourcer, f.eks.\nNavngivningen af underressourcen bør følge navne fra modelleringen, jf. retningslinje R27.\nREST 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.\nREST ressourcer skal returnere hypertext links til alle relevante informationer om ressourcen, når ressourcen tilgås, jf.\nREST 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 serviceudbyderen ikke at forpligte sig til disse hypertext links’ værdier. Serviceanvenderen bør ikke opbevare URI’erne til relaterede objekter, men skal fremfinde dem hver gang, hvilket giverserviceudbyderen bedre muligheder for at foretage ændringer, uden at serviceanvenderen påvirkes.\nREST arkitekturstilen [HATEOAS] samt [MATURITY] påpeger, at REST webservices skal returnere metainformationer om ressourcer via hypertext links. Hvis ressourcer returnerer relevante links som metadata, behøver serviceanvendere 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 serviceanvendere.\nREST 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 ressourcen.\nREST webservices vil ofte udstille ressourcer, der er samlinger af forretningsobjekter, 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.\nREST webservices skal understøtte standardiserede fremsøgningsparametre i det omfang, søgning understøttes af webservicen.\nEn REST webservice, der understøtter søgning skal understøtte at ressourcens URI kan suppleres med ”parametre” til søgning eller sortering, der anvendes ved læsning af ressourcer (ved brug af HTTP GET).\nSø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 serviceanvenderen 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ællesoffentlige webservices vil gøre det forståelsesmæssigt lettere at anvende sådanne webservices.\nFor at gøre det lettere at anvende en webservice for serviceanvendere, skal fremsøgninger i samlinger af forretningsobjekter anvende standardiserede søgeparametre. Ensretning af parametrene betyder, at serviceanvendere kan genbruge eksisterende erfaringer med søgning.\nRetningslinjen er affødt af forretningsbehov F6 og F2.\nStandardiseringen bør inkludere parametre for udvælgelse (query), sortering af resultater, selektion af returnerede attributter for fremsøgte ressourcer, samt information om hvorvidt relaterede ressourcer skal returneres.\nUnderstøttelsen af søgning skal dog afvejes over for retningslinje R01 om at minimere funktionalitet og målrette webservices.\nSøgning i ressourcer angives i URI som en query string med ”søgeoperator” ’q’ (dvs. ”?q=alder%3d20”).\nSortering ved ressourcesøgninger angives i URI som query string med ”søgeoperator” ’sort’ (dvs. ”?sort=alder”).\nSelektering af attributter ved ressourcesøgninger angives i URI som query string med ”søgeoperator” ’fields’ (dvs. ”?fields=navn,adresse”).\nEmbedding af relaterede objekter ved ressourcesøgninger angives i URI som query string med ”søgeoperator” ’embed’ (dvs. ”?embed=barn”).\nDe faktisk understøttede søgemuligheder skal målrettes de faktiske behov, jf. retningslinjerne R01.\nNår serviceanvendere bruger REST webservices, der udstiller samlinger med mange objekter, vil serviceanvenderen typisk ønske at kunne fremsøge objekterne gradvist for at forbedre svartider på søgning. En REST webservice kan understøtte dette ved at tillade ”paginering” (søgeresultater kan indlæses ”sidevist”). Paginering er en velkendt teknik, hvor webservicen giver serviceanvenderen mulighed for at indikere et antal ønskede objekter, samt hvorfra søgningen skal ”fortsætte”.\nREST webservices, der udstiller store samlinger af forretningsobjekter, skal understøtte paginering i forbindelse med den søgning, webservicen understøtter.\nWebservices kan indeholde et stort antal objekter og relaterede objekter.\nWebservicen bør i de tilfælde understøtte delvis afhentning af søgeresultater (dvs. paginering), så serviceanvender ikke altid modtager hele søgeresultatet.\nWebservices, der tilgår store mængder af objekter, bør understøtte pagineringsparametre under fremsøgning. Pagineringen bør anvende en eksplicit ”cursor” (f.eks. elementidentifikator eller position), der skal medsendes fra serviceanvenderen. Serviceudbyderen kan lade sig inspirere af internet RFC 50057.\nDet samlede antal objekter, der udgør søgningens resultat bør medsendes, hvis dette kendes af webservicen.\nServiceudbyderen bør dokumentere, hvordan pagineringen påvirkes, hvis der sker ændringer til samlingen af objekter, mens pagineringen pågår.\nDe understøttede muligheder for paginering skal målrettes de faktiske behov, jf. retningslinjerne R01.\nREST 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.\nJSON 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.\nREST ressourcers data skal repræsenteres i JSON eller XML. Webservicen skal returneres i det format, som serviceanvenderen ønsker, hvis det er muligt.\nXML har stor udbredelse i fællesoffentlige webservices (der konkret udstilles som SOAP services). Mange udviklingsteknologier understøtter validering af XML (specificeret via XSD), og udstilling som domæneobjekter i programmeringssproget (via autogenereret kode).\nDet vurderes dog vigtigst, at den repræsentation, en ressource udstilles med, er relevant for forretningsdomænet.\nNogle 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.\nHvis 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æsentation af komplekse datastrukturer normalt er tilstrækkelige i disse formater.\nServiceudbyderen skal udstille data til serviceanvendere.\nHvis der til data findes datastandarder inden for serviceudbyderens 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.\nRetningslinjen er affødt af forretningsbehov F6, F8, F9 og F2.\nHvis 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 standardiseret dataformat er velegnet til transmission via REST og HTTP.\nREST ressourcer skal i deres kommunikation deklarere, hvilke datarepræsentationer (f.eks. JSON, XML), de understøtter.\nHvis en REST ressource deklarerer de understøttede repræsentationer, er det muligt for serviceanvenderen at vælge den bedst egnede, således at webservicen målretter sig serviceanvenderens behov.\nRetningslinjen er affødt af forretningsbehov F6, F9 og F2.\nREST webservices skal udstille og deklarere, hvilken datarepræsentation de tilgængelige ressourcer har. REST webservices, der tilgås via HTTP, har yderligere den mulighed, at alternative datarepræsentationer kan tilbydes. En ressource 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).\nREST ressourcer bør via en HTTP header altid tilkendegive, hvilke repræsentationer ressourcen understøtter, når ressourcen returneres fra serviceudbyderen, fx ved et opslag eller en opdatering.\nNå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 specialtegn ’æøå’, men også tegn der ofte anvendes i navne, f.eks. ’äëöüé’. Tekstkodning er ofte en udfordring med især ældre it-løsninger, der udstiller webservices, eller når data fra en database udstilles direkte.\nTekst, herunder navne, beskrivelser mm. skal overføres mellem serviceanvender og serviceudbyder i et internationaliseret overførselsformat, UTF-8 eller tilsvarende, med mindre en anvendt domænespecifik standard tilsiger andet.\nDe danske specialtegn samt tegn fra EU og andre lande anvendes bredt i webservices. Serviceudbyder og serviceanvender skal vide sig sikre på, at tegn overføres korrekt. UTF-8 standarden skal anvendes hertil, da den sikrer korrekt overførsel og er i stand til at repræsentere alle nødvendige tegn.\nRetningslinjen er affødt af forretningsbehov F6 og F9.\nUdstillede webservices skal sikre, at tekst, der skal returneres til eller modtages fra serviceanvender, konverteres, såfremt teksten ikke efterfølgende opbevares og behandles i UTF-8. Hvis teksten skal konverteres, er webservicen ansvarlig for konverteringen.\nEn undtagelse i denne forbindelse er, hvis en domænespecifik standard, der anvendes til webservicens datarepræsentation, fastlægger et andet format.\nREST 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.\nHTTP består af en request struktur og en response struktur. I request strukturen angiver serviceanvenderen HTTP metoden (verbet), der skal gøre noget ved ressourcen, som er udpeget vha. en URI. I request headeren angives desuden parametre og andre metadata for forespørgslen. Eksempelvist kan der vha. authorization vedlægges et sikkerhedstoken. Det kan også være parametre for cache, tekstkodning, dato mv. I request body angives en evt. inputstruktur for kaldet.\nI response-strukturen angives en HTTP statuskode. I response headeren angives parametre og metadata for svaret. I response body sendes ressourcens repræsentation, som er det faktiske beskedindhold, typisk i form af en XML eller JSONstruktur. 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.\nREST webservices skal anvende HTTP som kommunikationsprotokol ved kald fra serviceanvender til den udstillede webservice og følge Bilag 4 ”Specifikation for brug af HTTP til REST”\nHTTP 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.\nRetningslinjen er affødt af forretningsbehov F1, F6 og F8. Retningslinjen præciserer OIO serviceprincippet ”Services baseret på standarder”, jf. [OIOSVC].\nREST 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”\nHTTP indeholder en række mekanismer, der bidrager til effektiv brug af båndbredde, datarepræsentation, mv. Disse mekanismer skal anvendes af serviceanvender og serviceudbyder for at sikre effektiv kommunikation.\nServiceudbyderen skal anvende HTTP således, at effektiv kommunikation med REST webservices understøttes.\nHvis serviceudbyderen tillader brug af bestemte HTTPmekanismer, kan kommunikationen mellem serviceanvender og serviceudbyder effektiviseres. Understøttelse af forhandling af ønsket datarepræsentation mellem webservicen og serviceanvenderen målretter webservicen til den konkrete brug. Understøttelse af komprimering af forespørgsel og svar reducerer krav til netværksbåndbredden.\nRetningslinjen er affødt af forretningsbehov F1, F6 og F8.\nhttp standardens ”content negotiation” mekanisme anvendes for at aftale datarepræsentation mellem serviceanvender og serviceudbyder.\nHTTP kompression af forespørgsler og svar skal understøttes, eventuelt implementeret i selve HTTP serveren8.\nREST webservices skal anvende HTTP sikkert ved udstilling af ressourcer.\nREST webservices skal sikre anvendelse af HTTP. Webservices skal kræve sikre forbindelser, f.eks. HTTPS eller kryptering og autentifikation via en anden mekanisme. De URI’er, der anvendes til ressourcer, bør ikke indeholde fortrolige 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.\nEndelig 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 eventuelt kunne søge på følsomme eller fortrolige data (f.eks. personnummer).\nServiceudbyderen skal tilskynde, at HTTP anvendes på en sikker måde af serviceanvenderen. Dette kan serviceudbyderen 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.\nRetningslinjen er affødt af forretningsbehov F1 og F10.\nWebservices bør returnere specifikke fejlkoder, hvis serviceanvenderen bruger usikker HTTP (dvs. uden kryptering og autentificering) i stedet for automatisk at omstille serviceanvenderen til en sikker HTTP.\nREST webservices bør kun udstille URI’er, der ikke indeholder nøgler af følsom karakter, f.eks. personnumre eller sikkerhedsinformationer.\nHvis 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.\nREST Webservices skal anvende OIOIDWS REST profile 1.0 ved håndtering af data\nHTTP og REST arkitetkturstilen angiver ikke entydigt, hvorledes\nSAML tokens udveksles. REST service skal anvende OIOIDWS REST profile 1.0, således at SAML tokens angives ensartet og med de ønskede metadata.\nAngivelse af SAML information i HTTP kan medføre problemer med platformsunderstøttelse. Anvendelse af OIOIDWS REST profile 1.0 sikrer, at SAML understøttelsen virker på tværs af udviklingsplatforme.\nOIO IDWS REST Profile 1.0 : https://www.digitaliser.dk/resource/526486/artefact/OIOIDWSRESTprofileV1_0.pdf?artefact=true&PID=3066971\nRetningslinjen sikrer, at SAML implementeringen i REST webservices 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 identifikation 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.\n[FODS] Digitaliseringsstyrelsen (2016) Den fællesoffentlige digitaliseringsstrategi 2016-2020,. Tilgængelig på: https://www.digst.dk/Strategier/Strategi-2016-2020\n[FIELDING] Roy Thomas Fielding (2000)Architectural Styles and the Design of Network-based Software Architectures.\n[HVIDBOG] Digitaliseringsstyrelsen (2017) Den digitalt sammenhængende offentlige sektor – Hvidbog om arkitektur for digitalisering, version 1.0.. Tilgængelig på: http://arkitektur.digst.dk/node/241\n[MATURITY] Leonard Richardson (2008) Richardsons maturity model, Tilgængelig på: https://martinfowler.com/articles/richardsonMaturityModel.html\n[MODEL] Digitaliseringsstyrelsen (2017) Fællesoffentlige regler for begrebs- og datamodellering, version 2.1. Tilgængelig på https://arkitektur.digst.dk/node/81/\n[OIOIDWS] 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\n[OIOMØNSTRE] Digitaliseringsstyrelsen (2014)”Integrationsmønstre. Tilgængelig på http://arkitekturguiden.digitaliser.dk/integrations-moenstre\n[OIOREST] It- og Telestyrelsen (2009) OIOREST i praksis – guidelines baseret på eksempler\n[OIOSVC] Digitaliseringsstyrelsen (2014)Serviceprincipper”. Tilgængelig på: http://arkitekturguiden.digitaliser.dk/serviceprincipper\n[REGEL7.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/node/460\n[W3C] W3C Working Group (2004) Definition af webservices og relation til REST. Tilgængelig på: http://www.w3.org/TR/wsarch/#relwwwrest\nAppendiks A Eksempel på anvendelse\nI det følgende anskuliggøres retningslinjerne for webservices anvendelse af REST ved brug af et eksempel om lokalebooking.\nLokalestyrelsen ønsker at udstille en webservice til lokalebooking. Der er følgende funktionalitet og data:\nSom medarbejder skal jeg kunne se en liste af tilgængelige mødelokaler for et givent tidspunkt.\nSom medarbejder skal jeg kunne oprette en ny booking i et givent mødelokale og angive tidsrummet, hvor mødet kan finde sted, for at kunne afholde et internt eller eksternt møde.\nSom mødeadministrator skal jeg kunne se, hvornår en booking er foretaget, samt hvornår den skal gælde fra og til.\nJf. retningslinjerne skal ressourcer udstilles som navneord og svare til forretningsmodelleringens begreber.\n”Lokaler” er således en liste over styrelsens mødelokaler.\n”Bookinger” er en liste over et mødelokales bookinger.\nHer kunne man vælge, om sammenhængen mellem lokaler og bookinger omfatter, at en booking kunne omfatte flere mødelokaler. I dette tilfælde vælger styrelsen, at en booking kun kan omfatte ét lokale.\nDet giver følgende URI’er for afhentning af ressourcer:\nHent bookinger for et lokale\nHent en booking\nEt møde har Tidsrum er fra og til og Registreringstid er egenskaber ved en booking.\nOpdateringer 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.\nTilsvarende kan deltaopdateringer ikke udføres, hvorfor der ikke understøttes PATCH.\nAvendelse af temporalitet\nFor at overholde retningslinjerne for webservices, designes lokalebookingservicen desuden med følgende temporale dimensioner:\nDet er kun muligt at booke et lokale, såfremt det er ledigt på bookingtidspunktet.\nDet er ikke muligt at booke et lokale bagud i tid.\nDet er kun muligt at booke et lokale maksimalt to timer ad gangen.\nDer skal være minimum tre timer mellem møder, som brugeren ønsker at booke til.\nFor at sikre integritet af bookingerne, designes servicen med en operation ’Booking’:\nhttp://lokalebooking.dk/ressourcer/lokaler/<id>/bookinger/<id> Booking kan kaldes med HTTP Put med følgende parametre:\nGyldigTil = [dateTime].\nServicen 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 lokalebookingen, ikke har en booking på dette eller andre lokaler inden for tre timer af GyldigTil tidspunktet. Hvis disse betingelser er opfyldt, opretter Servicen en ny bookingressource og returnerer 200, hvis ikke returneres en fejlkode.\nDet er dermed muligt at oprette en booking, som overholder alle temporale forretningsregler og har indkapslet denne logik over for serviceanvendere. Dermed overholdes retningslinje R18.\nServicen skal kunne forespørge, om et lokale er ledigt for en given periode, hvorfor der er behov for at kunne fremsøge dette på en given lokaleressource. Hertil anvendes HTTP GET:\nOvenstående servicekald returnerer alle bookinger, som er foretaget på et givent lokale i den angivne periode. Hvis svaret fra servicen er 204 (no content), betyder det, at lokalet er ledigt på det pågældende tidspunkt.\nHvis 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 bookingressourcen:\nServicen skal kunne fremfinde tidligere registreringer, således at der er fuld sporbarhed på bookinger (oprettelser, ændringer og aflysninger), som er foretaget på et givent lokale.\nDet er muligt at angive søgeparametre på flade:\nHerved returneres indholdet af den seneste registrering inden [tidspunkt.] En anden mulighed for at angive søgeparametre på flade er som følger\nHerved returneres en liste af bookinger svarende til samtlige registreringer i intervallet.\nAppendiks B Liste over retningslinjer:\nUdstil minimal funktionalitet og data i den enkelte webservice\nSeparér webservices fra konkret implementering\nSeparér webservices fra eksterne afhængigheder\nUnderstøt gentagne forsøg på kald fra serviceanvenderen\nKræv specifikke informationer ved ansvarsoverdragelse ved kald til webservices\nDokumentér udstillede webservices i overensstemmelse med den fællesoffentlige dokumentationsramme for webservices\nOpmærk webservices i henhold til fællesoffentlige emnesystematikker\nOpmærk webservices med følsomhed eller fortrolighed af data\nDokumentér servicespecifikke fejlkoder for webservices\nDokumentér drift af forskellige versioner af webservices\nAnvend semantisk versionering af webservices\nViderefør gamle versioner, når en webservice ændres\nLog alle kald til webservices\nAnvend transaktionsidentifikatorer ved kald og svar\nAnvend requestID ved kald og svar\nUnderstøt monitorering af udstillede webservices\nReturnér servicespecifikke fejl som standardiserede fejlmeddelelser\nForretningsregler vedrørende temporaler indkapsles og håndhæves på serviceniveau\nWebservices med temporale ressourcer returnerer som et øjebliksbillede\nWebservices med temporale ressourcer anvender anerkendte nøgleord i søgeparametre.\nWebservices med temporale ressourcer skal udstille ensartet funktionalitet til revision og Linje\nWebservices med temporale ressourcer skal anvende ens håndtering af tidspunkter\nWebservices skal have tokenbaseret sikkerhed\nUdstil webservices som REST ressourcer\nUdstil data som REST ressourcer\nModellér REST ressourcer med udgangspunkt i forretningsmodellering\nNavngiv REST ressourcer ud fra forretningsmodellens begreber\nNavngiv REST ressourcer ud fra REST arkitekturstilen\nUdstillede REST ressourcer har unikke, sikre identifikatorer\nUdstil REST ressourcers relaterede entiteter\nReturnér REST ressourcer med hypertext links\nAnvend standardiserede REST fremsøgningsparametre\nUnderstøt søgning med delresultater\nRepræsentér REST ressourcer i et standardiseret dataformat\nDeklarér REST ressourcer datarepræsentationer\nOverfør tekst i en internationaliseret repræsentation\nAnvend HTTP som fællesoffentlig REST kommunikationsprotokol\nAnvend HTTPs mekanismer til effektiv kommunikation\nAnvend HTTP sikkert til REST ressourcer\nREST webservices skal anvende OIO IDWS REST profile V1.0\n1 For eksempel er der forskel på krav til webservices, der udstiller offentligt tilgængelige data, og webservices der udstiller personoplysninger til udveksling mellem myndigheder.\n2 Et eksempel på en generisk webservice er en webservice, der tillader generel søgning i en mændge udstillede forretningsobjekter, hvis indre repræsentation (attributter og relationer) direkte gøres tilgængelig for serviceanvendere.\n3 Svarende til Single Responsibility princippet fra SOLID (https://en.wikipedia.org/wiki/SOLID_(objectoriented_design)).\n4 Semantisk versionering er en oversættelse af ”Semantic Versioning”, der er beskrevet her: http://semver.org\n5 Dette betegnes som ’Command Query Responsibility Segregation’. Se http://udidahan.com/wpcontent/uploads/Clarified_CQRS.pdf for en uddybning.\n6 En fællesoffentlig standard kan evt. fastlægges for at sikre ensartethed.\n7 Se f.eks.: https://tools.ietf.org/html/rfc5005\n8 Flere gængse HTTP servere kan opsættes til komprimering og dekomprimering af data, f.eks. Apache HTTPd.\nPermanent URL til artiklen: https://arkitektur.digst.dk/node/1094\nTitel Retningslinjer for webservices\nDe fælles retningslinjer for webservices er en vejledning til serviceudbydere, der skal udstille data og funktionalitet via webservices. Vejledningen skal opfattes som en beskrivelse af god praksis og skal hjælpe serviceudbyderen, når denne designer og udstiller webservices rettet imod serviceanvendere.


Kviklån - Finansmagasinet\nEt kviklån er til dig, der står i en uheldig situation hvor der er opstået en uforudset udgift, hvor du har brug for penge hurtigt til den pågældende regning eller reparation. Med et kviklån kan du nemt og hurtigt optage et lån og have rådighed over beløbet samme dag. Hastigheden og kravet til sikkerhed gør et kviklån til et nemt lån, hvorpå du kan låne penge i en fart, hvis uheldet er ude.\nEt kviklån er en form for forbrugslån som kan foretages hurtigt, hvoraf navnet kviklån opstår. I modsætning til et almindeligt forbrugslån, kan du med et kviklån ofte kun låne op til 6.000 kr., men til gengæld er ansøgningsprocessen kort og nem, og du har pengene på kontoen inden for 1-2 dage. Ved de fleste typer af kviklån kan du sende ansøgningen til lånet online, hvorefter du får svar i løbet af et par timer. Denne hurtige behandlingstid skyldes blandt andet at der ikke skal stilles sikkerhed, at beløbet er forholdsvis lavt og at kravet til personoplysninger er minimalt. Hastigheden af hvornår pengene er på din konto, vil afhænge af hvilken bank du har, som låneudbyderen skal overføre pengene til. Ofte vil omkostningerne ved at optage et online kviklån være noget højere end hvis du optager det i en bank, men i visse perioder og under visse omstændigheder kan gebyrerne og omkostningerne være stort set de samme.\nDer kan være flere gode grunde til at vælge at optage et kviklån. Det er for eksempel et godt alternativ til det traditionelle banklån, hvor du er nødt til at møde op i banken og snakke med en bankrådgiver, før du kan få bevilget lånet. Især når beløbet ikke er større end højest 6.000 kr., så kan det godt virke kompleks og tidskrævende, at skulle igennem den traditionelle låneprocess i banken. Derudover er et kviklån et overskueligt lån med en kort løbetid, og du har derfor hurtigt fået gælden ude af verden igen. Vilkårene er simple; du vælger selv beløbet du vil låne og typisk vil du skulle betale beløbet tilbage inden for 15-60 dage.\nHvornår er det fordelagtigt med et kviklån?\nOfte skal man helst passe på med at optage for mange kviklån, da man hurtigt kan komme til at skylde mange penge væk, men i enkelte tilfælde kan det alligevel være ganske fordelagtigt at gøre brug af et kviklån. Eksempler kunne være at:\nDer pludselig er opstået en uforudset udgift, som du ikke har penge til at betale\nDu har nogle regninger, der skal betales inden du får løn\nDu ved, at du har mulighed for hurtigt at betale beløbet tilbage igen\nDer opstår en unik mulighed, som kun er gældende i en begrænset periode.\nDu mangler penge til indkøb sidst på måneden\nHvad skal du være opmærksom på med et kviklån?\nPå et kviklån betaler man ofte en noget højere rente, end man ville gøre på et lidt større lån med en længere løbetid. Hvis du overvejer at optage et kviklån, skal du derfor være særligt opmærksom på renten, eller den såkaldte ÅOP. Det er den procentdel af det samlede lånebeløb, som du skal betale i renter om året. Det er derfor dette tal, som du skal kigge på når du skal sammenligne de forskellige lånetyper. Med et kviklån vil du dog næppe opleve de store udgifter, da lånebeløbet i forvejen er meget lille, og lånet hurtigt er tilbagebetalt pga. den korte tilbagebetalingsperiode. Uanset hvad bør du gøre dig klart, om du har økonomisk mulighed for at tilbagebetale kviklånet, når det engang skal indfries. Hvis dette ikke er tilfældet bør du hellere overveje en anden type lån.