Fælles retningslinjer for webservices. UDKAST version 0.9 December 2017

Transkript

1 Fælles retningslinjer for webservices UDKAST version 0.9 December 2017

2 Indhold 1. Indledning Afgrænsning Læsevejledning Oversigt over retningslinjer 6 2. Principper og for retningslinjer 8 3. Generelle retningslinjer for webservices Fokus på serviceanvendere Ansvarsfordeling ved kald til webservices Servicedokumentation Serviceversionering Servicelogning Servicetilgængelighed Servicefejlmeddelelser Temporale ressourcer Sikkerhedskrav til webservices Retningslinjer for REST webservices Modellering af REST webservices Søgninger i REST webservices Datarepræsentation i REST webservices REST kommunikationsprotokol Sikkerhedskrav til REST webservices Referenceliste Appendiks A Eksempel på anvendelse Avendelse af temporalitet Appendiks B Liste over retningslinjer: 53

3 Side 3 af Indledning Dette dokument beskriver fællesoffentlige retningslinjer for anvendelse af webservices og særligt REST (Representational State Transfer) webservices i itløsningerne i den offentlige sektor. Formålet med de fælles retningslinjer for webservices er at skabe bedre interoperabilitet imellem offentlige institutioners it-løsninger. Retningslinjerne er udsprunget af Hvidbog om arkitektur for digitalisering (jf. [HVIDBOG]), hvor retningslinjerne er en konkretisering af princip 7 og 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 De 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. Definitioner: Webservices 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: o REST-compliant Web services, in which the primary purpose of the service is to manipulate XML representations of Web resources using a uniform set of "stateless" operations; and o arbitrary Web services, in which the service may expose an arbitrary set of operations. REST er en arkitekturstil, der anvendes til udstilling af ressourcer (data) med webservices. REST er baseret på principperne og arkitekturen, som anvendes på internettet, og genbruger få, udbredte standarder og protokoller herfra, f.eks. HTTP. [ FIELDING]. En 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 anven-

4 Side 4 af 54 delige, hvor der ikke foreligger domænespecifikke standarder og retningslinjer for webservices. 1.1 Afgrænsning Retningslinjerne har følgende væsentlige afgrænsninger: Retningslinjerne stiller ikke krav til, at offentlige institutioner skal anvende REST over andre arkitekturstile, når data og funktionalitet skal udstilles via webservices. Serviceanvendere 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. Retningslinjerne 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. Retningslinjerne stiller krav til logning i forbindelse med webservicens anvendelse, og dokumentet indeholder ikke retningslinjer, som sikrer overholdelse af bestemt lovgivning, fx GDPR. Retningslinjerne i dette dokument kan den enkelte organisation vælge at anvende inden for egen organisation for at skabe mere ensartede snitflader på tværs af it-løsninger, men det er ikke et krav. 1.2 Læsevejledning Dokumentet er opbygget i fem hovedafsnit. Nærværende afsnit 1 udgør en kort indledning. Afsnit 2 indeholder en redegørelse for de principper og, der ligger til grund for de angivne retningslinjers udformning. Afsnit 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. Afsnit 4 indeholder en angivelse af retningslinjer, der er specifikke for REST webservices. Afsnit 5 indeholder en referenceliste. Afsnit 6 indeholder et tværgående eksempel. Dokumentet henviser til følgende bilag:

5 Side 5 af 54 Bilag 1 Dokumentation for REST Webservices Bilaget giver uddybende beskrivelse af retningslinje R06. Bilag 2 Fejlstruktur og fejlkoder for REST Webservices omhandler ensretning af fejlstrukturer for webservices og ensartet anvendelse af HTTP headers og håndtering af asynkrone kald. Bilag 3 Nonfunktionelle krav til realisering af retningslinjer indeholder et kravbilag, som kan anvendes af serviceudbydere til at kravstille webservices, som overholder retningslinjerne. Bilag 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.

6 Side 6 af Oversigt over retningslinjer Dokumentet indeholder følgende retningslinjer opdateret efter tema. Generelle retningslinjer for webservices Fokus på serviceanvendere R01. Udstil minimal funktionalitet og data i den enkelte webservice R02. Separér webservices fra konkret implementering R03. Separér webservices fra eksterne afhængigheder Ansvarsfordeling ved kald til webservices R04. Understøt gentagne forsøg på kald fra serviceanvenderen R05. Kræv specifikkke informationer ved ansvarsoverdragelse ved kald til webservices Servicedokumentation R06. Dokumentér udstillede webservices i overensstemmelse med den fællesoffentlige dokumentationsramme for webservices R07. Opmærk webservices i henhold til fællesoffentlige emnesystematikker R08. Opmærk webservices med følsomhed eller fortrolighed af data R09. Dokumentér servicespecifikke fejlkoder for webservices R10. Dokumentér drift af forskellige versioner af webservices Serviceversionering R11. Anvend semantisk versionering af webservices R12. Viderefør gamle versioner, når en webservice ændres Servicelogning R13. Log alle kald til webservices R14. Anvend transaktionsidentifikatorer ved kald og svar R15. Anvend requestid ved kald og svar Servicetilgængelighed R16. Understøt monitorering af udstillede webservices Servicefejlmeddelelser R17. Returnér servicespecifikke fejl som standardiserede fejlmeddelelser Temporale ressourcer R18. Forretningsregler vedrørende temporaler indkapsles og håndhæves på serviceniveau R19. Webservices med temporale ressourcer returnerer som et øjebliksbillede R20. Webservices med temporale ressourcer anvender anerkendte nøgleord i søgeparametre. R21. Webservices med temporale ressourcer skal udstille ensartet funktionalitet til revision og Linje R22. Webservices med temporale ressourcer skal anvende ens håndtering af tidspunkter Sikkerhedskrav til webservices R23. Webservices skal have tokenbaseret sikkerhed

7 Side 7 af 54 Retningslinjer for REST webservices Modellering af REST webservices R24. Udstil webservices som REST ressourcer R25. Udstil data som REST ressourcer R26. Modellér REST ressourcer med udgangspunkt i forretningsmodellering R27. Navngiv REST ressourcer ud fra forretningsmodellens begreber R28. Navngiv REST ressourcer ud fra REST arkitekturstilen R29. Udstillede REST ressourcer har unikke, sikre identifikatorer R30. Udstil REST ressourcers relaterede entiteter R31. Returnér REST ressourcer med hypertext links Søgninger i REST webservices R32. Anvend standardiserede REST fremsøgningsparametre R33. Understøt søgning med delresultater Datarepræsentation i REST webservices R34. Repræsentér REST ressourcer i et standardiseret dataformat R35. Deklarér REST ressourcer datarepræsentationer R36. Overfør tekst i en internationaliseret repræsentation REST kommunikationsprotokol R37. Anvend HTTP som fællesoffentlig REST kommunikationsprotokol R38. Anvend HTTPs mekanismer til effektiv kommunikation R39. Anvend HTTP sikkert til REST ressourcer Sikkerhedskrav til REST webservices R40. REST webservices skal anvende OIO IDWS REST profile V1.0 Retningslinjerne beskrives efter følgende mønster: Navn Retningslinje Rationale Understøttede Implikation Angiver nummeret og navnet på retningslinjen Beskriver retningslinjen klart og præcist Beskriver forretningsværdien ved at følge retningslinjen Beskriver de konkrete, som retningslinjen understøtter Beskriver hvilken indvirkning, retningslinjen har på forretningsmæssig og teknisk implementering Fø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.

8 Side 8 af Principper og for retningslinjer Retningslinjerne 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, som retningslinjerne udmønter. Principper og i dette afsnit har således udgjort grundlaget for udarbejdelsen af retningslinjerne, der fremgår af afsnit 3 og 4. Den organisation, som ønsker at anvende retningslinjerne, bør undersøge, om organisationen har, der adskiller sig væsentligt fra de her anførte. 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, der er vigtigst. Principper Følgende tre principper gælder for alle retningslinjerne: Retningslinjerne skal kunne anvendes bredt af offentlige institutioner, samt andre organisationer der ønsker at anvende dem. Retningslinjerne skal baseres på viden fra anvendelser af eksisterende retningslinjer for webservices, bl.a. fra SKAT, Sundhedsdatastyrelsen, Grunddataprogrammet, KOMBIT m.fl. Retningslinjerne skal være langtidsholdbare, men samtidig være tilstrækkeligt konkrete og implementeringsnære til, at retningslinjerne kan inddrages af initiativerne i digitaliseringsstrategien. Forretningsbehov er opdelt i tre overordnede temaer. Tema 1: Forretningsbehov vedrørende serviceanvendere og serviceudbydere Temaet 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. F1. 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

9 Side 9 af 54 realiseres af serviceudbydere ved brug af eksisterende og velbeskrevne metoder samt udbredte værktøjer og rammeværk. F2. Design af webservices skal tage udgangspunkt i serviceanvenderens behov. Det vil sige, at webservices udstilling af data og funktionalitet er intuitiv og enkel at anvende for en serviceanvender. F3. Ændringer i webservices skal udformes således, at det er så omkostningseffektivt som muligt for serviceanvendere. Æ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. F4. 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. F5. Webservices skal kunne understøtte forandringer i serviceanvenderes forretningskrav ved hurtigt at kunne understøtte ændringer i data og funktionalitet samt hurtigt at kunne skalere til ændret forbrug heraf. Tema 2: Forretningsbehov vedrørende data og funktionalitet Temaet fokuserer på behovene for, at udstilling af data via webservices sker på en måde, som sikrer mest mulig interoperabilitet. F6. REST webservices skal udstille forretningsobjekter som ressourcer på en ensartet måde for at sikre interoperabilitet, jf. afsnit 2.1. F7. Udstilling af webservices skal omfatte dokumentation af de pågældende webservices, herunder dokumentation af regler for syntaks og semantik samt beskrivelse af snitfladen. Dokumentationen skal være tilgængelig både for personer og it-systemer. F8. REST webservices skal anvende relevante eksisterende og kommende fællesoffentlige datastandarder og profiler for REST ved udvikling af nye versioner af en REST webservice. F9. Webservices skal udstille data i bredt anvendte dataformater.

10 Side 10 af 54 F10. Webservices skal tage højde for, at data kan have forskellige grader af fortrolighed, hvilket stiller forskellige krav 1 til egenskaberne ved en webservice. Fx kan en webservice udstille personoplysninger. Tema 3: Forretningsbehov vedrørende stabil og sikker driftsafvikling Temaet omhandler behovene for, at webservices kan indgå i et fællesoffentligt itlandskab på en forvaltningsmæssig sikker og effektiv måde. F11. Serviceudbydere skal kunne dokumentere anvendelsen af data og funktionalitet i webservices, herunder webservicens håndterinng af svartider og fejlsituationer. F12. Webservices skal kunne overvåges, og transaktioner skal kunne spores på tværs af webservices. Webservices skal udstille tilstrækkelige data til at kunne indgå i orkestrering, herunder indeholde dubletkontrol og ensartet struktur af fejlbeskeder. F13. Webservices skal kunne udstille adgang til data og funktionalitet af 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. 1 For eksempel er der forskel på krav til webservices, der udstiller offentligt tilgængelige data, og webservices der udstiller personoplysninger til udveksling mellem myndigheder.

11 Side 11 af Generelle retningslinjer for webservices Dette afsnit indeholder retningslinjer, der understøtter ene 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 Fokus på serviceanvendere En webservice skal være så enkel at anvende som muligt. En webservice er enkel, når dens operationer udstiller en afgrænset mængde data og funktionalitet på en entydig måde for en bestemt serviceanvendelse. Dette medfører et større antal operationer og webservices, som er dedikeret til et bestemt forretningmæssigt formål. Ved ændringer i 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. En webservice, som udstiller generiske operationer 2, 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. Navn: R01. Udstil minimal funktionalitet og data i den enkelte webservice Retningslinje Webservices skal designes således, at én webservice kun udstiller tilstrækkelig data eller funktionalitet for at give forretningsmæssig mening for en bestemt serviceanvendelse. Rationale En ændring til data og funktionalitet skal som udgangspunkt kun medføre ændringer i den webservice, der udstiller 2 Et eksempel på en generisk webservice er en webservice, der tillader generel søgning i en mændge udstillede forretningsobjekter, hvis indre repræsentation (attributter og relationer) direkte gøres tilgængelig for serviceanvendere.

12 Side 12 af 54 Understøttede Implikation funktionaliteten. På denne måde minimeres behovet for ændringer i etablerede serviceanvenderes klienter. Serviceanvenderes klienter skal kun ændres, hvis ændringen påvirker deres serviceanvendelse. Retningslinjen understøtter F2 og F3, idet den medfører, at serviceanvendere samlet set påvirkes mindre. En webservice løser ideelt set kun én opgave 3, 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. Et 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. Et 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. En mere serviceanvenderrettet tilgang kunne fx være at anvende en service eller operation per serviceanvendelse, fx opret booking, opdater mødelokale attributter. I dette eksempel vil en tilføjelse af et nyt obligatorisk attribut på mødelokalet ikke påvirke serviceanvendere, som kun anvender funktionen opret booking. 3 Svarende til Single Responsibility princippet fra SOLID ( ).

13 Side 13 af 54 Navn: R02. Separér webservices fra konkret implementering Retningslinje Webservices skal designes, så de afkobler implementeringen af interne og eksterne forretningsobjekter fra den snitflade, der udstilles imod serviceanvendere. Rationale Ved at anvende en facade, der afskærmer serviceanvenderen fra den konkrete implementering af data og funktionalitet i udbyderens interne miljø, vil serviceudbyderen opnå større friheder i implementeringen af webservicen. Understøttede Retningslinjen er affødt af F3 ved at afskærme serviceanvenderen fra udbyderens interne, flygtige og evt. irrelevante anvendelse af data og funktionalitet Implikation Ved servicedesign bør det afdækkes, netop hvilke dele af et forretningsobjekt, der er behov for at gøre tilgængelige for anvendere. Webservicens design bør give disse dele en repræsentation, der ikke fastholder serviceudbyderen i den samme konkrete implementering af webservicen i hele servicens levetid. Navn: R03. Separér webservices fra eksterne afhængigheder Retningslinje Webservices skal designes, så snitfladen udstiller egne datasæt og ikke har eksterne afhængigheder til andre domæners objekter. Rationale Nå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. Understøttede Retningslinjen er affødt af F3 ved at afskærme serviceanvenderen fra fremmede forretningsobjek- ter. Implikation Ved servicedesign skal det afdækkes, hvilke dele af data der er behov for at gøre tilgængelige for anvendere. Samtidigt vil anvendelsen af facader dog øge omkostningen ved ændringer i bagvedliggende webservices, da facaden skal opdateres.

14 Side 14 af Ansvarsfordeling ved kald til webservices Ved integrationer mellem forskellige myndigheders it-systemer er det centralt, at ansvaret for gennemførsel og fejlhåndtering ved en transaktion er tydeligt 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. Æ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. Navn: R04. Understøt gentagne forsøg på kald fra serviceanvenderen Retningslinje En webservice skal entydigt kunne håndtere gentagne forsøg fra serviceanvenderen. Rationale En klar ansvarsplacering i forbindelse med gennemførsel af kald er nødvendig for, at informationer og evt. ansvar for behandling overdrages korrekt. Det er kun serviceanvenderen, der kan afgøre, om svaret på et kald er modtaget. Understøttede Retningslinjen er affødt af F4. Implikation Det er serviceanvenderen, der er ansvarlig for at gennemføre et kald, herunder at genforsøge kaldet, indtil et svar (en fejl eller en kvittering) modtages fra webservicen. Hvis ansvarsoverdragelsen kræver, at et bagvedliggende forretningssystem skal opdateres asynkront, så gælder det, at REST webservices skal følge mønsteret for asynkrone kald, som beskrevet i Bilag 2 Fejlstruktur og fejlkoder for REST Webservices. Webservices kræver, at en serviceanvender medsender en transaktionsidentifikator ved alle kald, jf. retningslinje R14, derfor kan transaktionsidentifikatoren anvendes af serviceudstiller til at detektere gentagne forsøg, og håndtere gentagelsen korrekt. Navn: R05. Kræv specifikke informationer ved ansvarsoverdragelse ved kald til webservices Retningslinje Webservices, 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.

15 Side 15 af 54 Rationale Understøttede Implikation Det skal være uomtvisteligt, hvornår en offentlig institution eller en organisation (som serviceanvender) har overdraget et ansvar til en anden myndighed eller en organisation (som serviceudbyder). For at sikre dette skal webservicen kræve, at serviceanvenderen har inkluderet specifikke 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. Retningslinjen er affødt af F4. Serviceudbyderen skal designe webservicen således, at eksplicitte overdragelsesinformationer skal være til stede i et korrekt kald til webservicen. Disse informationer kan fx omfatte: Identifikation af den ansvarsafgivende organisation/myndighed. Identifikation af den ansvarsmodtagende organisation/myndighed. En unik identifikator af denne ansvarsoverdragelse. En identifikation af hvilket ansvar, der overdrages, f.eks. ved reference til en aftalt klassifikation, emnesystematik eller lovgrundlag. Serviceudbyderen skal realisere webservicen, så den returnerer et kvitteringssvar, der indikerer, at ansvaret er overdraget. Så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. 3.3 Servicedokumentation Serviceudbydere 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.

16 Side 16 af 54 Serviceanvenderes behov består af forretningsforståelse og teknisk forståelse af data, der udveksles, samt koblingen mellem forretningsmodeller og konkrete datarepræsentationer. Forretningsmæssige krav om data og funktionalitet af den udstillede webservice er en central del af dokumentationen, der skal give serviceanvenderen tilstrækkelig viden. Navn: R06. Dokumentér udstillede webservices i overensstemmelse med den fællesoffentlige dokumentationsramme for webservices Retningslinje Dokumentationen for webservices skal følge den fællesoffentlige dokumentationsramme, der udgøres af Bilag 1 Dokumentation for REST Webservices. Rationale God dokumentation er opdelt og opmærket på en måde, der gør, at dokumentationens enkeltdele målrettes de 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. Alle 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. Understøttede Implikation Dokumentationen 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. Serviceudbyderen mindsker ressourceforbruget i sin support, når let tilgængelig dokumentation medfører, at serviceanvenderen kan finde de relevante dele af dokumentationen. Retningslinjen er affødt af F2. Krav til dokumentationen fremgår af den fællesoffentlige dokumentationsramme for webservices, som er beskrevet i Bilag 1 Dokumentation for REST Webservices. Dokumentation af webservices skal overholde de krav, som er angivet i Bilag 1 afsnit 2 og skal stille tilsvarende dokumentation til rådighed, jf. Bilag 1 afsnit 3. For 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.

17 Side 17 af 54 Navn: R07. Opmærk webservices i henhold til fællesoffentlige emnesystematikker Retningslinje Serviceudbyderen skal opmærke udstillede webservices i henhold til fællesoffentlige emnesystematikker. Rationale Serviceudbyderen skal opmærke webservices i henhold til emnesystematik, således at serviceanvendere tydeligt kan se, hvilken offentlig forvaltning, forvaltningsproces eller anden proces hos serviceudbyderen, webservicen er udstillet i 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. Understøttede Retningslinjen er affødt af F2 Implikation Dokumentationen 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. Opmærkningen beskrives for den enkelte webservice. Hvis en webservice indgår i flere forvaltningsprocesser eller forvaltningsemner, skal alle emnerne angives i dokumentationen. Opmærkningen for REST webservices skal foretages som angivet i Bilag 1 Dokumentation for REST Webservices. Navn: R08. Opmærk webservices med følsomhed eller fortrolighed af data Retningslinje Serviceudbyderen 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. Rationale Serviceudbyderen 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. Understøttede Retningslinjen er affødt af F2. Implikation Opmæ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.

18 Side 18 af 54 Opmærkningen påføres den enkelte webservice i form af angivelse af fortroligheds- eller følsomhedsniveauer fra en klassifikation af niveauer i den fællesoffentlige dokumentationsramme. En REST webservice skal opmærke følsomhed og fortrolighed i OpenAPI, jf. Bilag 1 Dokumentation for REST Webservices afsnit Hvis 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. Serviceanvenderen 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. Navn: R09. Dokumentér servicespecifikke fejlkoder for webservices Retningslinje Alle servicespecifikke fejl, der kan returneres fra en webservice, skal dokumenteres, og dokumentationen skal indgå i webservicens dokumentation og gøres tilgængelig for serviceanvendere. Rationale Serviceanvendere 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. Understøttede Retningslinjen er affødt af F2. Implikation Dokumentationen for webservices skal inkludere en oversigt over alle servicespecifikke fejl, samt dokumentation af hver enkelt servicespecifik fejl. Dokumentationen af den enkelte servicespecifikke fejl bør angive, hvilken fejlkode (en værdi) fejlen er identificeret ved, en fejlbeskrivelse og årsag. Dokumentationen af servicespecifikke fejl er en del af webservicens dokumentation og skal udstilles til serviceanvendere. Fejlhåndtering for serviceudbyder omfatter ikke fejl i infrastrukturen mellem serviceanvender og webservice.

19 Side 19 af 54 Fejlbeskrivelser og statuskoder for REST webservices skal overholde retningslinjerne for servicefejlmeddelelser, jf. Bilag 4 Specifikation for brug af HTTP til REST og afsnit 3.7.Fejlstrukturer for alle webservices skal overholde fejlstrukturen beskrevet i bilag 4. Serviceudbydere vil øge interoperabiliteten ved at tydeliggøre ændringer til webservices, så serviceanvendere kan afgøre, om ændringens effekt fordrer konsekvensændringer hos dem selv. Navn: R10. Dokumentér drift af forskellige versioner af webservices Retningslinje Serviceudbyderen skal dokumentere vilkårene i forbindelse med samtidig driftsafvikling af versioner af den samme webservice. Rationale Serviceanvendere kan få fordel af at være tydeligt 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). Understøttede Retningslinjen er affødt af F2. Implikation Serviceudbyderen 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. Det bør fremgå af dokumentationen: Hvordan webservices versioneres i henhold til R11. Hvor længe gensidigt inkompatible webservices udstilles i flere udgaver, samt antallet heraf. Om, og i givet fald hvor længe i forvejen, serviceudbyderen adviserer serviceanvendere om ændringer. Hvordan serviceanvendere eventuelt kan identficere sig over for serviceudbyder. Hvordan serviceudbyderen udstiller en oversigt over konkrete datoer for publicering af nye webservices

20 Side 20 af 54 samt ændringer til og nedlæggelse af eksisterende webservices. 3.4 Serviceversionering Det er centralt for serviceanvendere, at de er i stand til at afgøre, om en ændring til en webservice kræver korresponderende ændringer hos serviceanvenderen. Konsekvenserne af sådanne ændringer skal generelt minimeres. Når ændringer er nødvendige, skal webservicens version tydeligt indikere over for serviceanvenderen, om webservicen er kompatibel med den tidligere udgave. Ved kompatibilitet forstås i denne forbindelse, at én version af en webservice er kompatibel med en tidligere version, hvis der ingen ændringer kræves hos serviceanvenderen. Versionering 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: To versioner af en webservice med forskellige major versioner (f.eks. 1.1 og 2.0) er ikke kompatible. En serviceanvender, der anvender version 1.1 af webservicen, vil skulle foretage ændringer for at kunne anvende version 2.0 af webservicen. Nå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. Hvis 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 4 Semantisk versionering er en oversættelse af Semantic Versioning, der er beskrevet her:

21 Side 21 af 54 serverens DNS navn i en HTTP URI for en REST ressource dette opfattes derfor som en ikke-kompatibel ændring. Navn: R11. Anvend semantisk versionering af webservices Retningslinje Webservices skal anvende semantisk versionering til at tydeliggøre kompatibilitet og overholde versioneringsreglerne. Rationale Serviceanvendere skal gøres tydeligt opmærksomme på, hvornår ændringer til en udstillet webservice er kompatibel med eksisterende serviceanvendelser, og hvornår dette ikke er tilfældet. Semantisk versionering indeholder flere komponenter i et versionsnummer, der gør dette klart: ændringer i major komponenten i servicens versionsnummer betyder brud på kompatibilitet med eksisterende serviceanvendelser. Understøttede Retningslinjen er affødt af F2 og F3. Implikation Webservices skal garantere kompatibilitet mellem versioner af en webservice ifølge reglerne for semantisk versionering. Webservices kan eventuelt understøtte, at serviceanvenderen kan specificere den ønskede version af webservicen i forbindelse med et kald. En konsekvens af denne versionering er, at følgende ændringer generelt medfører en ny major version: En valgfri kaldsparameter bliver obligatorisk. Tilføjelse af en ny obligatorisk parameter ved kald. Fjernelse af værdier i svar. Semantiske ændringer af data i kald eller svar Listen er ikke udtømmende. Andre ændringer, som fx ændring af sikkerhedsmodel og sletning af udstillede attributter eller relationer, er normalt en ikke-kompatibel ændring. Andre ikke-kompatible ændringer, der kræver nyt versionsnummer, er f.eks. introduktion af nye obligatoriske parametre eller begrænsning i mængden af mulige parametre. Navn: R12. Viderefør gamle versioner, når en webservice ændres Retningslinje Serviceudbyderen skal videreføre versioner i en tilstrækkelig overgangsperiode. Rationale Når der sker ikke-kompatible ændringer til udstillede 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.

22 Side 22 af 54 Understøttede Implikation Eksisterende 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. Retningslinjen er affødt af F2 og F3. Hvis æ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 R Servicelogning Logning og juridiske krav til logning er ikke færdig analyseret i version 0.9, dette afsnit er derfor ikke endeligt. I forbindelse med integration mellem it-løsninger er det nødvendigt, på 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. Navn: R13. Log alle kald til webservices Retningslinje Alle væsentlige kald til og svar fra webservices skal logges af serviceudbyderen. Rationale Det skal sikres, at alle væsentlige kald til en webservice 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. Understøttede Retningslinjen er affødt af F2, F12 og F11. Implikation Serviceudbyder skal logge alle kald til en given webservice, hvor følsomme eller fortrolige informationer behandles i henhold til relevant lovgivning. Serviceudbyder skal 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. Serviceudbyderen skal dokumentere, hvilke kald en given webservice logger.

23 Side 23 af 54 Webservicen skal desuden foretage logning af alle eksterne kald, der foretages som konsekvens af det modtagne kald, hvor fortrolige eller følsomme data er involverede. For at sikre at logningen hos serviceanvender og serviceudbyder kan sammenholdes, skal det enkelte kald være unikt identificeret. En sådan identificering har form af en unik transaktionsidentifikator. Navn: R14. Anvend transaktionsidentifikatorer ved kald og svar Retningslinje Webservices skal kræve en transaktionsidentifikator ved kald og skal returnere transaktionsidentifikator ved svar. Serviceudbyder sender transaktionsidentifikator med videre, hvis forespørgslen giver anledning til kald videre til andre webservices Rationale Det skal være muligt for serviceanvendere og serviceudbydere at spore sammenhængen i servicekald på tværs. Understøttede Retningslinjen er affødt af F1, F12 og F11. Implikation Serviceudbyderen skal kræve, at serviceanvenderen medsender en globalt/universelt unik transaktionsidentifikator for hvert kald til en udstillet webservice. Transaktionsidentifikatoren kan f.eks. være et UUID, jf. ietf RFC Webservicens svar skal inkludere transaktionsidentifikatoren fra kaldet. Webservices sender transkationsidentifikatoren med videre, hvis forespørgslen giver anledning til kald videre til andre webservices. Navn: R15. Anvend requestid ved kald og svar Retningslinje Webservices skal logge et unikt requestid ved hvert kald, og ved gensendelse af et svar skal samme RequestID anvendes. Rationale Entydighed af det enkelte kald giver mulighed for sporing på tværs af services. Det 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. Understøttede Retningslinjen er affødt af F1, F12 og

24 Side 24 af 54 F11. Implikation Serviceudbyderen skal medsende en unik requestid for hvert kald til en udstillet webservice. RequestID kan f.eks. være et universelt unikt id, jf. internet RFC Servicetilgængelighed Monitorering af tilgængelighed til anvendte webservices kan bistå håndtering af løsning eller omgåelse af fejl i it-landskabet. Serviceudbyderen skal derfor udstille informationer om webservicens tilgængelighed til serviceanvendere. Serviceanvendere kan anvende informationen til at afgøre, om en udstillet webservice er tilgængelig på et givet tidspunkt. Navn: R16. Understøt monitorering af udstillede webservices Retningslinje Udstillede webservices skal understøtte, at serviceanvenderen kan monitorere webservicens tilgængelighed. Rationale Serviceanvendere har ved unormale driftssituationer behov for at afgøre, om anvendte webservices er tilgængelige eller ikke, og om eventuelle driftsforstyrrelser er placeret hos serviceanvenderen eller hos serviceudbyderen. Udstilling af dedikeret monitoreringsfunktionalitet har typisk større robusthed end de webservices, der anvendes til forretningsprocesserne. Understøttede Retningslinjen er affødt af F2. Implikation Udstillede webservices skal udstille en snitflade, som viser, om en webservice er tilgængelig eller ikke. Monitoreringen kan enten være inkluderet som en dedikeret (del)funktionalitet af en udstillet webservice eller være udstillet som en sideordnet webservice. Udstillede 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. Det er centralt, at monitoreringen ikke foretager opdaterin-

25 Side 25 af 54 ger 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. 3.7 Servicefejlmeddelelser Når fejl opstår i forbindelse med behandling af et kald til en udstillet webservice, er det vigtigt for efterfølgende analyse af fejlen, at tilstrækkelige informationer om fejlen er leveret til serviceanvenderen. Serviceanvenderen skal selv kunne analysere fejlens detaljer og ved hjælp af den modtagne dokumentation afgøre, hvordan fejlen efterfølgende skal håndteres. Dette stiller væsentlige krav til de informationer, der returneres af en udstillet webservice i forbindelse med fejl. Fejlbeskrivelser er uddybet i Bilag 2 Fejlstruktur og fejlkoder for REST Webservices. Navn: R17. Returnér servicespecifikke fejl som standardiserede fejlmeddelelser Retningslinje Webservices skal returnere servicespecifikke fejl som standardiserede fejlmeddelelser til serviceanvenderen med dokumenterede fejlkoder som beskrevet i Bilag 2 Fejlstruktur og fejlkoder for REST Webservices. Rationale Dokumentationen af fejlmeddelelser skal angive over for serviceanvenderen, om kaldet er idempotent. 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. For 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. For 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. Meget 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. Webservices 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

26 Side 26 af 54 og headere, som er beskrevet i bilag 2. Serviceanvendere er afhængige af præcise og især fyldestgørende fejlmeddelelser, således at serviceanvenderen gøres i stand til at håndtere fejlen enten manuelt eller automatisk. En utilstrækkelig fejlmeddelelse medfører, at serviceanvenderen ikke vil kunne udføre fejlhåndtering. Data eller opdateringer af data kan dermed gå tabt. Understøttede Implikation Retningslinjen er affødt af F2, F6 og F12. Retningslinjen præciserer OIO serviceprincippet Services returnerer sigende fejlmeddelelser, jf. [OIOSVC]. Fejlmeddelelser vedrørende servicespecifikke fejl returneres i den fællesoffentlige struktur for fejlmeddelelser, jf. Bilag 2 Fejlstruktur og fejlkoder for REST Webservices. Fejlmeddelelser skal anvendes i kontekst af den valgte transportprotokol, der også returnerer fejlkoder. For REST webservices gælder retningslinje R37. Det betyder, at transportprotokollens fejlkoder skal bruges korrekt, når servicespecifikke fejl returneres i svar.

27 Side 27 af Temporale ressourcer Der 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. Et eksempel på en temporal kan være et datostempel for, hvornår en ressource sidst er blevet ændret. Det vil sige, hvornår en given transaktion er gennemført for en ressource. Dette implementeres typisk som en traditionel logning, hvor det er muligt at danne historik over transaktioner, som har fundet sted på den pågældende ressource, se også eksemplet angivet i Appendiks A. Der er også andre dimensioner af temporaler, hvor man kan angive 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 Udstillet data, som indeholder mere end en enkelt temporal dimension, betegnes som en multi-temporal model. Typisk begrænser dette sig i praksis til to 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). Fx kan et mødelokales størrelse have forskellige værdier over tid, som skifter i forbindelse med renovering. Et lokale kan således være 12 m 2 fra , 20m og En administrator retter dog først størrelsen på det sidste mødelokale (20m 2 ) i Registreringen foretages således i 2016, men de 20m 2 er gyldige fra 2015, hvor den sidste renovering blev foretaget. Dette kan anskueliggøres med et eksempel, hvor en ressource opdateres på tre på hinanden følgende tidspunkter. For ressourcen foretages først en opdatering for periode 1 [g0;g1] til registreringstidspunktet r0. Efterfølgende opdateres 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.