Retningslinjer for webservices

Angiver nummeret og navnet på retningslinjen

Beskriver retningslinjen klart og præcist 

Beskriver forretningsværdien ved at følge retningslinjen

Beskriver de konkrete forretningsbehov, som retningslinjen understøtter

Beskriver hvilken indvirkning, retningslinjen har på forretningsmæssig og teknisk implementering

Æ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.

R01. Udstil minimal funktionalitet og data i den enkelte webservice

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.

En æ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.

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

En webservice løser ideelt set kun én opgave³, 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”.

R02. Separér webservices fra konkret implementering

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

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

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

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.

R03. Separér webservices fra eksterne afhængigheder

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

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.

Retningslinjen er affødt af forretningsbehov F3 ved at afskærme serviceanvenderen fra fremmede forretningsobjekter.

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.

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

En webservice skal entydigt kunne håndtere gentagne forsøg fra serviceanvenderen.

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. 

Retningslinjen er affødt af forretningsbehov F4. 

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.

R05. Kræv specifikke informationer ved ansvarsoverdragelse ved kald til webservices

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. 

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 forretningsbehov 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”.

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

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. 

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 forretningsbehov 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 og skal stille tilsvarende dokumentation til rådighed, jf. Bilag 1.

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.

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

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

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.

Retningslinjen er affødt af forretningsbehov F2.

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”.

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

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.

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. 

Retningslinjen er affødt af forretningsbehov F2.

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.

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”.

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.

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. 

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.

Retningslinjen er affødt af forretningsbehov F2.

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.

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

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

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).

Retningslinjen er affødt af forretningsbehov F2. 

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 samt ændringer til og nedlæggelse af eksisterende webservices.

R11. Anvend semantisk versionering af webservices

Webservices skal anvende semantisk versionering til at tydeliggøre kompatibilitet og overholde versioneringsreglerne.

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. 

Retningslinjen er affødt af forretningsbehov F2 og F3.

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.

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

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

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.

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 forretningsbehov 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 R10.

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

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.

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

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. 

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. 

R14. Anvend transaktionsidentifikatorer ved kald og svar

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

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

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

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 4122.

Webservicens svar skal inkludere transaktionsidentifikatoren fra kaldet. 

Webservices sender transkationsidentifikatoren med videre, hvis forespørgslen giver anledning til kald videre til andre webservices.

R15. Anvend requestID ved kald og svar

Webservices skal logge et unikt requestID ved hvert kald, og ved gensendelse af et svar skal samme RequestID anvendes.

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.

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

Serviceudbyderen skal medsende en unik requestID for hvert kald til en udstillet webservice. 

RequestID kan f.eks. være et universelt unikt id, jf. internet RFC 4122.

Udstillede webservices skal understøtte, at serviceanvenderen kan monitorere webservicens tilgængelighed.

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. 

Retningslinjen er affødt af forretningsbehov F2.

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 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.

R17. Returnér servicespecifikke fejl som standardiserede fejlmeddelelser

Webservices skal returnere servicespecifikke fejl som standardiserede fejlmeddelelser til serviceanvenderen med dokumenterede fejlkoder som beskrevet i Bilag 2 ”Fejlstruktur og fejlkoder for REST Webservices”. 

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 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.

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

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.

R18. Forretningsregler vedrørende temporaler indkapsles og håndhæves på serviceniveau

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

Serviceudbyderen skal sikre, at den udstillede service validerer input fra opdaterende servieoperationer, således at ressourcens integritet bevares gennem hele ressourcens levetid.

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

En 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 operationer⁵. Det betyder for et REST-baseret snitflade, at der skal udstilles dedikerede ressourcer, som opretter og vedligeholder udstillede data.

R19. Webservices med temporale ressourcer returnerer som et øjebliksbillede

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

Selvom 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.

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

Webservices, som udstiller søgning i temporale data, skal fremfinde det gældende øjebliksbillede på søgetidspunktet. Det medfører, at temporal funktionaltitet skal udstilles i særlige adskilte funktioner rettet mod givne forretningsbehov.

Webservices 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.

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

Webservices, 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.

Registreringstidspunkt er altid webservicens tidspunktet for modtagelse af kaldet og skal ikke udstilles som parameter.

Der 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.

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

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

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

Webservices, 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:

• ”GyldigFra”, der angiver starttidspunkt for gyldighed.
• ”GyldigTil”, der angiver sluttidspunkt for gyldighed.
• ”RegistreringFra”, der angiver starttidspunkt i et interval i en flade.
• ”RegistreringTil”, der angiver sluttidspunkt i et interval i en flade.

Da 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.

Et fremsøgning af en flade vil som oftest blive anvendt i væsentligt mindre grad end henholdsvis fremsøgning af et øjebliksbillede og Linje for en given temporal ressource.

Dette skal afspejles i designet af webservicen.

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

Webservices, 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).

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

GyldigFra er altid inkluderet i resultatet.

GyldigTil er altid ekskluderet i resultatet.

RegistreringFra er altid inkluderet i resultatet.

RegistreringTil er altid ekskluderet i resultatet.

Håndtering af angivne tidspunkter skal være ens for at understøtte interoperabilitet.

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

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

R23. Webservices skal have tokenbaseret sikkerhed

Webservices skal anvende tokenbaseret sikkerhed

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

Retningslinjen understøtter forretningsbehov F13 og F2.

Udveksling 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.

R24. Udstil webservices som REST ressourcer

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

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

Retningslinjen er affødt af forretningsbehov F6.     

De informationer, der udstilles om ressourcen, udgør en fast aftale (eller en ”kontrakt”) mellem serviceanvender og serviceudbyder. REST arkitekturstilen opererer ikke med kontrakter (WSDL) ligesom SOAP protokollen. I praksis er serviceanvender dog afhængig af en række informationer for let at kunne anvende en webservice. Disse 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.

I stedet for at udstille funktionalitet for forretningsoperationer på en webservice, er det selve objekterne, der udstilles som en web ressource og hentes via verber. 

En ressource skal altid identificeres af en URI.

De URI’er, der eksplicit udstilles til omverdenen, vil 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.

Operationer 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.

R25. Udstil data som REST ressourcer

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

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

Retningslinjen er affødt af forretningsbehov F6.   

Operationer 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.

R26. Modellér REST ressourcer med udgangspunkt i forretningsmodellering

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

Udstillede REST ressourcer bør struktureres ud fra den bagvedliggende forretningsmodellering. De begreber og informationsentiteter, forretningsmodelleringen af et givet domæne har afdækket, bør anses som kandidater til 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.

Modellering af ressourcer efter [MODEL] sikrer ensartet sprogbrug og fælles grundlag for at fastlægge granularitet og serviceboundaries. Det letter og tydeliggør den 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.

Retningslinjen er affødt af forretningsbehov F6.

Udstillede ressourcer skal have oprindelse i en modellering af forretningens begreber og informationer. 

Udgangspunktet for ressourcerne skal være forretningsmodelleringens ”forretningsobjekter” med egenskaber. Relaterede entiteter udstilles i udgangspunktet som separate entiteter, jf. retningslinje R30.

Forretningsmodellering kan være en konsekvens af domænerelateret standardisering, f.eks. HL7/FHIR på sundhedsområdet. 

Der henvises til retningslinje R34 vedrørende repræsentation af ressourcers data.

R27. Navngiv REST ressourcer ud fra forretningsmodellens begreber

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

Et 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. 

Retningslinjen er affødt af forretningsbehov F1 og F6.

Ressourcer navngives fra domænets begreber, f.eks. ”sager”, ”journalnotater”, ”parter”. Betegnelserne kan være en konsekvens af domænerelateret standardisering, f.eks.

HL7/FHIR på sundhedsområdet. Se også retningslinje R28 vedrørende konkret navngivning.

R28. Navngiv REST ressourcer ud fra REST arkitekturstilen

REST ressourcer skal navngives som navneord, jf. REST arkitekturstilen, og skal navngives tilsvarende serviceudstillers forretningsbegreber.

For 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”.

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

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

R29. Udstillede REST ressourcer har unikke, sikre identifikatorer

Alle udstillede REST ressourcer skal have unikke identifikatorer (URI’er), der er stabile og sikre.

REST 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.

Stabile identifikatorer sikrer, at data kan genfindes i ressourcernes levetid.

REST ressourcers unikke identifikatorer skal være unikke, hvilket betyder, at de kun må udpege én ressource. 

Det skal være muligt for serviceanvendere at opbevare udstillede ressourcers identifikatorer. 

Identifikatorerne skal være sikre, hvilket betyder, at de ikke må indeholde personoplysninger, da identifikatorerne typisk vil indgå i den krævede logning af adgang til ressourcen, jf. retningslinje R13. 

Retningslinjen er affødt af forretningsbehov F6 og F1.

Serviceudbyderen 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. 

R30. Udstil REST ressourcers relaterede entiteter

REST ressourcer skal udstilles sine entiteter ved at følge de fællesoffentlige regler for begrebs- og datamodellering [MODEL]. 

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

Entiteter, der udstilles som REST ressourcer, vil ofte have relationer til andre entiteter. 

Relaterede 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.

REST 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. 

Retningslinjen er affødt af forretningsbehov F6 og F1.

REST webservices bør udstille relaterede forretningsobjekter som underressourcer, f.eks.

”/sager/<sagsid>/journalnotater/<notatid>”.

Navngivningen af underressourcen bør følge navne fra modelleringen, jf. retningslinje R27.

R31. Returnér REST ressourcer med hypertext links

REST ressourcer skal returnere hypertext links til alle relevante informationer om ressourcen, når ressourcen tilgås, jf.

REST arkitekturstilen. 

REST webservices udstiller eksplicit en række ressourcer med velkendte URI’er. I det omfang relaterede objekter udstilles via hypertext links, er det en fordel for 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.

REST 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.

Retningslinjen er affødt af forretningsbehov F6 og F1.

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

R32. Anvend standardiserede REST fremsøgningsparametre

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

En 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).

Søgeparametrene kan understøtte, at der angives værdier for ønskede attributter eller tilstedeværelsen af relationer. Når de udvalgte konkrete instanser er fremsøgt, kan 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.

For 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.

Retningslinjen er affødt af forretningsbehov F6 og F2.

Standardiseringen 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.

Understøttelsen af søgning skal dog afvejes over for retningslinje R01 om at minimere funktionalitet og målrette webservices.

• Søgning i ressourcer angives i URI som en query string med ”søgeoperator” ’q’ (dvs. ”?q=alder%3d20”).
• Sortering ved ressourcesøgninger angives i URI som query string med ”søgeoperator” ’sort’ (dvs. ”?sort=alder”).
• Selektering af attributter ved ressourcesøgninger angives i URI som query string med ”søgeoperator” ’fields’ (dvs. ”?fields=navn,adresse”).
• Embedding af relaterede objekter ved ressourcesøgninger angives i URI som query string med ”søgeoperator” ’embed’  (dvs. ”?embed=barn”).

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

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

Webservices kan indeholde et stort antal objekter og relaterede objekter. 

Webservicen bør i de tilfælde understøtte delvis afhentning af søgeresultater (dvs. paginering), så serviceanvender ikke altid modtager hele søgeresultatet.

Retningslinjen er affødt af forretningsbehov F6 og F2.

Webservices, 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 5005⁷.

Det samlede antal objekter, der udgør søgningens resultat bør medsendes, hvis dette kendes af webservicen.

Serviceudbyderen bør dokumentere, hvordan pagineringen påvirkes, hvis der sker ændringer til samlingen af objekter, mens pagineringen pågår. 

De understøttede muligheder for paginering skal målrettes de faktiske behov, jf. retningslinjerne R01.

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

REST ressourcers data skal repræsenteres i JSON eller XML. Webservicen skal returneres i det format, som serviceanvenderen ønsker, hvis det er muligt.

XML 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). 

Det vurderes dog vigtigst, at den repræsentation, en ressource udstilles med, er relevant for forretningsdomænet. 

Nogle domæner som fx geodataområdet og sundhedsområdet har i væsentligt omfang egne standarder (henholdsvis OGC og HL7/FHIR). En domænespecifik, standardiseret repræsentation foretrækkes derfor, da de syntaktiske og semantiske forhold ofte er afklarede og veldokumenterede. 

Hvis der på et forretningsområde ikke findes en standard for datarepræsentation, er JSON eller XML velegnet som generel datarepræsentation, da mulighederne for repræsentation af komplekse datastrukturer normalt er tilstrækkelige i disse formater. 

Serviceudbyderen skal udstille data til serviceanvendere.

Hvis 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. 

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

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

R35. Deklarér REST ressourcer datarepræsentationer

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

Hvis 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.

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

REST 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).

REST 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.

Tekst, 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.

De 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.

Retningslinjen er affødt af forretningsbehov F6 og F9.

Udstillede 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.

En undtagelse i denne forbindelse er, hvis en domænespecifik standard, der anvendes til webservicens datarepræsentation, fastlægger et andet format.

R37. Anvend HTTP som fællesoffentlig REST kommunikationsprotokol

REST 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”

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

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

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

R38. Anvend HTTPs mekanismer til effektiv kommunikation

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

Hvis 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.

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

http standardens ”content negotiation” mekanisme anvendes for at aftale datarepræsentation mellem serviceanvender og serviceudbyder.

HTTP kompression af forespørgsler og svar skal understøttes, eventuelt implementeret i selve HTTP serveren⁸.

R39. Anvend HTTP sikkert til REST ressourcer

REST webservices skal anvende HTTP sikkert ved udstilling af ressourcer.

REST 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. 

Endelig skal det sikres, at eventuelle HTTP servere, der er placerede ”foran” udstillede webservices, ikke logger den dynamiske del af URI’en (query string), da en søgning eventuelt kunne søge på følsomme eller fortrolige data (f.eks. personnummer).

Serviceudbyderen 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.

Retningslinjen er affødt af forretningsbehov F1 og F10.

Webservices 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. 

REST webservices bør kun udstille URI’er, der ikke indeholder nøgler af følsom karakter, f.eks. personnumre eller sikkerhedsinformationer. 

Hvis udstillede REST webservices anvender en foranstillet HTTP server, må denne ikke logge HTTP ”query string” eller andre evt. følsomme eller fortrolige data, da denne logning ellers skal hånderes som følsomme data.

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

HTTP og REST arkitetkturstilen angiver ikke entydigt, hvorledes

SAML tokens udveksles. REST service skal anvende OIOIDWS REST profile 1.0, således at SAML tokens angives ensartet og med de ønskede metadata.

Angivelse af SAML information i HTTP kan medføre problemer med platformsunderstøttelse. Anvendelse af OIOIDWS REST profile 1.0 sikrer, at SAML understøttelsen virker på tværs af udviklingsplatforme.

OIO IDWS REST Profile 1.0 : https://github.com/digst/OIOIDWS.Net

F13, F2

Retningslinjen 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.

Hent lokaler

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

Hent lokale

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

Hent bookinger for et lokale

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

Hent en booking

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

R01.

Udstil minimal funktionalitet og data i den enkelte webservice

R02.

Separér webservices fra konkret implementering

R03.

Separér webservices fra eksterne afhængigheder

R04.

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

R05.

Kræv specifikke informationer ved ansvarsoverdragelse ved kald til webservices

R06.

Dokumentér udstillede webservices i overensstemmelse med den fællesoffentlige dokumentationsramme for webservices

R07.

Opmærk webservices i henhold til fællesoffentlige emnesystematikker

R08.

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

R09.

Dokumentér servicespecifikke fejlkoder for webservices

R10.

Dokumentér drift af forskellige versioner af webservices

R11.

Anvend semantisk versionering af webservices

R12.

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

R13.

Log alle kald til webservices

R14.

Anvend transaktionsidentifikatorer ved kald og svar

R15.

Anvend requestID ved kald og svar

R16.

Understøt monitorering af udstillede webservices

R17.

Returnér servicespecifikke fejl som standardiserede fejlmeddelelser

R18.

Forretningsregler vedrørende temporaler indkapsles og håndhæves på serviceniveau

R19.

Webservices med temporale ressourcer returnerer som et øjebliksbillede

R20.

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

R21.

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

R22.

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

R23.

Webservices skal have tokenbaseret sikkerhed

R24.

Udstil webservices som REST ressourcer

R25.

Udstil data som REST ressourcer

R26.

Modellér REST ressourcer med udgangspunkt i forretningsmodellering

R27.

Navngiv REST ressourcer ud fra forretningsmodellens begreber

R28.

Navngiv REST ressourcer ud fra REST arkitekturstilen

R29.

Udstillede REST ressourcer har unikke, sikre identifikatorer

R30.

Udstil REST ressourcers relaterede entiteter

R31.

Returnér REST ressourcer med hypertext links

R32.

Anvend standardiserede REST fremsøgningsparametre

R33.

Understøt søgning med delresultater

R34.

Repræsentér REST ressourcer i et standardiseret dataformat

R35.

Deklarér REST ressourcer datarepræsentationer

R36.

Overfør tekst i en internationaliseret repræsentation

R37.

Anvend HTTP som fællesoffentlig REST kommunikationsprotokol

R38.

Anvend HTTPs mekanismer til effektiv kommunikation

R39.

Anvend HTTP sikkert til REST ressourcer

R40.

REST webservices skal anvende OIO IDWS REST profile V1.0