Bilag 3 - Nonfunktionelle krav til realisering af retningslinjer

Body:

Dette dokument indeholder nonfunktionelle krav til brug af webservices i it-understøttelsen af den offentlige sektor. Dokumentet er bilag 3 til hoveddokumentet ”Fælles retningslinjer for webservices”, jf. [WEBSER]. Retningslinjerne for webservices er udarbejdet med henblik på at være bredt anvendelige i den offentlige sektor. I hoveddokumentet beskrives de arkitekturprincipper og forretningsbehov, som ligger til grund for retningslinjerne og dermed de nonfunktionelle krav i dette bilag. De nonfunktionelle krav understøtter realiseringen af webservices, der overholder de fælles retningslinjer for webservices.

De nonfunktionelle krav her i bilag 3 kan anvendes i aftaler mellem offentlige institutioner og it-leverandører til udvikling og vedligehold af it-systemer, som udstiller webservices til tværoffentlig it-understøttelse. Kravene er målrettet fastprisaftaler. Kravene kan dog også indgå i en product backlog til brug for aftale om agil udviklingsmetode.

Når kravene skal anvendes i forbindelse med en konkret aftale, bør den ordregivende offentlige institution vurdere, om kravenes form og terminologi skal tilpasses til den konkrete situation, fx i anvendelsen af terminologi og kravtyper.

Dette afsnit indeholder indledning samt præsenterer målgruppen, dennes behov og afgrænsninger i dokumentet.

Afsnittet Terminologi, beskriver den anvendte terminologi for de nonfunktionelle krav. En offentlig institution, som ønsker at anvende de nonfunktionelle krav, skal sikre, at terminologien i dette bilag svarer til terminologien i den aftale, som den offentlige institution ønsker at indgå.

Afsnittet Nonfunktionelle krav, indeholder en liste af de nonfunktionelle krav, der kan anvendes til realisering af webservices i overensstemmelse med retningslinjerne i hoveddokumentet [WEBSER].

Afsnittet Kilder, indeholder en liste over dokumentreferencer.

Målgruppe

Målgruppen for dette dokument er som følger:

Offentlige ansatte, der arbejder med it-udbud, herunder it-arkitekter med ansvar for de nonfunktionelle krav.
Serviceanvendere, som ønsker viden om anvendelse af webservices, der udstilles til brug mellem offentlige institutioner.

Afgrænsning

Dette dokument indeholder et eksempel på nonfunktionelle krav, der kan anvendes til realisering af webservices i overensstemmelse med retningslinjerne i hoveddokumentet [WEBSER]. Ordregivere kan i stedet vælge at udarbejde egne nonfunktionelle krav til realisering af webservices under overholdelse af retningslinjerne.

Dokumentet afgrænser sig til nonfunktionelle krav, som kun vedrører [WEBSER]. Dokumentet forholder sig dermed ikke til generelle nonfunktionelle krav vedrørende it-systemer eller understøttelse af lovgivning som fx forvaltningsloven og offentlighedsloven.

Terminologi

I dette afsnit beskrives den terminologi, som anvendes i udformningen af de nonfunktionelle krav. Terminologien er formuleret med henblik på, at kravene kan anvendes i et aftalegrundlag.

Tabel 1 Terminologi for bilaget
Term	Forklaring
Krav (K)	Et krav skal ikke nødvendigvis opfyldes af tilbudsgiver, men indgår i konkurrencen af den udbudte opgave/aftale. Tilbudsgivers besvarelse af et krav indgår således i ordregivers evaluering af det pågældende tilbud.
Leverandør	Leverandøren er en virksomhed, som er blevet tildelt den udbudte opgave/aftale.
Mindstekrav (MK)	Et mindstekrav skal opfyldes og skal indgå i tilbuddet. Kravet skal være opfyldt ved tidspunktet for overtagelsesprøven. Opfyldes kravet ikke, eller tages der forbehold herfor, anses tilbuddet for ikke-konditionsmæssigt. Mindstekrav indgår ikke i tilbudsevalueringen.
Operation	En webservice udstiller funktionalitet ved en eller flere operationer.
Ordregiver	Ordregiver, som konkurrenceudsætter en opgave.
REST	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, fx HTTP. [ FIELDING].
Serviceanvender	Serviceanvender er tredjepart, som anvender udstillede webservices.
Serviceudbyder	Serviceudbyder som udstiller webservices til serviceanvendere.
Systemet	It-systemet, der skal leveres i henhold til nærværende aftale.
Tilbudsgiver	En virksomhed som afgiver tilbud på en aftale.
Transaktionsidentifikator	Et unikt id som medsendes til webservices af serviceanvender.
Webservice	Webservices er defineret i [W3C]: “A Web service is a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-processable format (specifically WSDL).” ”We can identify two major classes of Web services: 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 arbitrary Web services, in which the service may expose an arbitrary set of operations. “
Webservicedokumentation	Webservicedokumentation indeholder enhver udarbejdet beskrivelse relateret til webservices i systemet, herunder brugerdokumentation, installationsdokumentation samt applikationsdriftsdokumentation.

Format af kravbeskrivelsen

Krav i dette dokument anvender formatet beskrevet i dette afsnit. Tekst markeret med ”gul” baggrund er det område, hvor en tilbudsgiver kan skrive. Tekst markeret med ”kursiv” er ment som tekst, der fjernes fra den endelige version af kontrakten.

Mindstekrav

Et Mindstekrav (MK) er opstillet ved brug af følgende skemaform:

MK#	Mindstekrav
	[Beskrivelse af MK]

Konkurrenceparametre

Et krav (K) er opstillet ved brug af følgende skemaform:

K#	Titel:
	Beskrivelse [Beskrivelse af krav]
	[Tilbudsgivers besvarelse af krav]

Tilbudsgiver skal besvare, i hvilken grad og hvordan kravet opfyldes i feltet ”[Tilbudsgivers besvarelse af krav]”, for at besvarelsen kan indgå i vurderingen af tilbuddet. Dette gælder for hvert krav.

Tilbudsgiver skal eksplicit angive kravets opfyldelsesgrad ved at anvende en af følgende tre muligheder: ”ikke opfyldt”, ”delvist opfyldt” eller ”helt opfyldt”. Dette gøres ved at sætte kryds i et (1) af felterne.

Ordregiver kan angive, hvad der lægges vægt på i en tilbudsevaluering for hvert krav, dette er markeret med kursiv og bør udgå af den indgående aftale

Liste over krav og tilhørende retningslinjer

I dette afsnit beskrives hvilke krav og deres relation til retningslinjerne for webservices.

Tabel 2 Krav og retningslinjer
Krav	Generelle retningslinjer for webservices
K1 Udstil minimal funktionalitet og data i den enkelte webservice	R01
K2 Separér webservices’ logiske datamodel fra konkret implementering	R02,R03, R04
K3 Overdragelse af myndighedsansvar	R05
K4 Understøttelse af tokenbaseret sikkerhed	R23
K5 Dokumentér udstillede webservices i systemet	R06
K6 Dokumentér følsomhed for webservices	R06. R07, R08
K7 Bagudkompatibilitet i webservices i en tilstrækkelig overgangsperiode	R10, R12
K8 Logning af alle kald til webservices i systemet	R13
K9 Webservices skal udstille deres status	R16
K10 Anvend fejlstruktur ved fejlbeskeder i systemets webservices	R17
K11 Udstilling af temporaler i historik- og flader	R19, R21, R22
K12 Navngivning af REST ressourcer	R24, R26, R27, R28
K13 Udstilling af muligheder for datarepræsentation	R34
K14 Udstilling af datarepræsentation	R34
K15 Dokumentér udstillede REST webservices i systemet	R06
K16 Anvend standardiserede REST fremsøgningsparametre	R32, R37
K17 Anvendelse af HTTP header ved request (forespørgsler)	R32, R37
K18 Anvendelse af HTTP header ved Response	R32, R37
K19 Anvendelse af paginering	R33
K20 REST webservices skal returnere HTTP statuskoder	R17, R37, R38
K21 Asynkron opdatering af fagsystemer for REST webservices	R17, R38
K22 REST webservices understøtter OIOIDWS REST profile 1.0	R40
Mindstekrav
MK1 Dokumentationstyper af webservices i systemet	R06, R08
MK2 Anvendelse af semantisk versionering i webservices i systemet	R11
MK3 Identifikation af brugen af webservices i systemet	R14
MK4 Identifikation af et kald af webservices i systemet	R15, R31
MK5 Anvendelse af sprog	R17
MK6 Anvendelse af JSON og XML	R17
MK7 Encoding i operationer for webservices	R17, R36
MK8 Datoer i operationer for webservices	R17, R36
MK9 Anvendelse af temporaler i opdateringsfunktioner	R18, R19
MK10 Anvendelse af temporaler i almindelige søgefunktioner	R18, R20
MK11 Modellering af REST ressourcer	R26, R30
MK12 Stabile URI’er	R29
MK13 Dokumentation af REST webservices i systemet	R35
MK14 Dokumentationsformat for REST webservices i systemet	R06
MK15 Anvendelse af GET og POST	R25, R28
MK 16 Anvendelse af DELETE	R25, R28
MK17 Sikring af fejlhåndtering ved anvendelse af PUT og POST	R17, R38
MK18 Sikring af kald ved gentagelser ved delvis opdatering af et helt objekt i REST webservices	R17, R30
MK19 Kommunikationsprotokol ved REST webservices	R37
MK20 REST webservices skal kun kunne anvende HTTP sikkert ved udstilling af ressourcer	R39

Nonfunktionelle krav til generelle webservices

Dette afsnit stiller krav til arkitektur og design af webservices for at sikre kvaliteten af systemet og for at sikre interoperabilitet mellem serviceudbyder og serviceanvender. De nonfunktionelle krav til webservices i systemet er opdelt i følgende områder:

Generelle krav til udstilling af webservices.
Krav til webservicedokumentation.
Krav til versionering.
Krav til logning og monitorering.
Krav til udformning af fejlmeddelelser.
Krav til datarepræsentation.

Generelle krav til udstilling af webservices

De generelle krav til arkitektur understøtter retningslinjerne beskrevet i [WEBSER].

K1	Udstil minimal funktionlitet og data i den enkelte webservice
	Webservices skal designes således, at én webservice kun udstiller tilstrækkeligt data eller funktionalitet for at give forretningsmæssig mening for en bestemt serviceanvendelse.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes hver webservice er designet, samt hvorledes det sikres, at kun tilstrækkeligt data og funktionalitet er udstillet.

K2	Separér webservices’ logiske datamodel fra konkret implementering
	Webservices udstillede snitflade skal afkobles fra den logiske datamodel i systemet.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes hver webservices udstillede snitflade er afkoblet fra den logiske datamodel. Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes den logiske datamodel kan ændres, uden at snitfladen ændrer sig. Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes det sikres, at ændringer i eksterne data ikke påvirker webservicens snitflade.

Webservices kan anvendes til overdragelse af ansvar mellem offentlige institutioner i forbindelse med afgørelser eller faktisk forvaltningsvirksomhed. Fx kan en meddelelse om en afgørelse i en myndighed medføre, at en anden myndighed genoptager en sag.

K3	Overdragelse af myndighedsansvar
	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.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvilke overdragelsesinformationer, som webservices kræver. Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes der returneres en forretningskvittering for, at overdragelsen er accepteret af serviceudbyder.

K4	Understøttelse af tokenbaseret sikkerhed
	Webservices skal anvende tokenbaseret sikkerhed til autentifikation af serviceanvendere.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvordan serviceanvender kan få udstedt et token, hvorledes webservicen understøtter tokenbaseret sikkerhed, samt hvilke typer tokens som understøttes.

Krav til dokumentation

Serviceudbydere skal dokumentere alle udstillede webservices. Dokumentationen skal målrettes serviceanvenderens behov for information, både forretningsmæssigt og teknisk.

Retningslinjer og krav til webservicedokumentation er beskrevet i [WEBSER] og [Bilag 1] til [WEBSER].

K5	Dokumentér udstillede webservices i systemet
	Dokumentationen for webservices skal indeholde metadataelementerne fra den fællesoffentlige dokumentationsramme, jf. [Bilag 1]. Udstillede webservices skal opmærkes i henhold til fællesoffentlige emnesystematikker KLE og FORM.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes metadataelementerne dokumenteres og at dokumentationen er anvendelig for en serviceanvender.

MK1	Dokumentationstyper af webservices i systemet
	Webservicedokumentation for webservices skal indeholde dokumentationen beskrevet i [Bilag 1] punkt 2.1.2.

K6	Dokumentér følsomhed for webservices
	Webservicedokumentationen skal indeholde en angivelse af følsomhed/fortrolighed af data.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes fortrolighed og følsomhed angives for webservices, samt hvorledes serviceudbyder kan indgå aftaler mellem offentlige institutioner og serviceanvendere.

Krav til versionering

Versionering af webservices er beskrevet i [WEBSER]. Versionering anvendes til at tydeligt indikere over for serviceanvenderen, om webservicen er kompatibel med den tidligere udgave.

MK2	Anvendelse af semantisk versionering i webservices i systemet
	Webservices skal anvende semantisk versionering til at tydeliggøre kompatibilitet og overholde versioneringsreglerne. 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 funktionalitet 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.

K7	Bagudkompatibilitet i webservices i en tilstrækkelig overgangsperiode
	Serviceudbyderen skal videreføre versioner i en tilstrækkelig overgangsperiode.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes leverandøren sikrer, at overgangsperioden er tilstrækkelig, og at antallet af samtidige versioner af en webservice er så lavt som muligt.

Krav til logning og monitorering

Logning skal sikre, at anvendelsen af webservicen spores i forbindelse med drift.

K8	Logning af alle kald til webservices i systemet
	Alle kald til webservices skal logges i persistent lager.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes logning er implementeret, herunder lægger ordregiver særlig vægt på, hvorledes det sikres, at logning altid foretages under belastning og ved ikke-håndterede fejl.

MK3	Identifikation af brugen af webservices i systemet
	Webservices skal modtage en transaktionsidentifikator ved kald, og skal returnere transaktionsidentifikator ved svar. Systemet sender transaktionsidentifikator med videre, hvis forespørgslen giver anledning til kald til andre webservices, som ikke er en del af systemet.

MK4	Identifikation af et kald af webservices i systemet
	Webservices skal logge et unikt RequestID ved hvert kald, og ved gensendelse af et svar skal samme RequestID anvendes.

K9	Webservices skal udstille deres status
	Webservices skal udstille information om webservicens tilgængelighed.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes webservices i systemet udstiller information om webservicens tilgængelighed til serviceanvendere.

Krav til udformning af servicefejlmeddelelser

Webservices skal returnere en ensartet fejlstruktur på tværs af REST webservices og arbitrary webservices. Fejlstrukturens ensartethed sikrer, at serviceanvendere kan håndtere fejl mere effektivt og forudsigeligt. Struktur for fejlmeddelelser er beskrevet i [WEBSER] samt i [Bilag 2].

K10	Anvend fejlstruktur ved fejlbeskeder i systemets webservices
	Fejlmeddelelsen skal overholde struktur for fejlmeddelelser som beskrevet i [WEBSER] samt i [Bilag 2].
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes fejlstrukturen implementeres og felterne udfyldes.

MK5	Anvendelse af sprog
	Webservices skal om muligt returnere data på det sprog, som serviceanvenderen ønsker. Hvis det ikke er angivet af serviceanvenderen, eller det ønskede sprog ikke er understøttet i systemet, så returneres data på dansk.

MK6	Anvendelse af JSON og XML
	Webservices skal returnere alle svar inklusive fejlmeddelelser i XML eller JSON.

Tekst, herunder navne, beskrivelser mm., skal overføres mellem serviceanvender og serviceudbyder i et internationaliseret overførselsformat.

MK7	Encoding i operationer for webservices
	Webservices skal modtage kald og sende svar i UTF-8.

Datoer skal håndteres således, at format og tidszone håndteres.

MK8	Datoer i operationer for webservices
	Webservices skal anvende UTC formatet i datoer i udstillede snitflader.

Krav til anvendelse af temporaler

Dette afsnit beskriver krav til anvendelse af retningslinjer for temporaler, som er beskrevet i [WEBSER]. Der kan være behov for at angive forskellige tidsmæssige aspekter af en ressource – såkaldte temporaler – i en webservice, jf. [WEBSER]. Disse krav gælder kun, hvis webservicen udstiller temporale data. Webservices, som udstiller bitemporale ressourcer, skal returnere det øjebliksbillede for registrering og gyldighed, som er gældende for fremsøgningstidspunktet.

MK9	Anvendelse af temporaler i opdateringsfunktioner
	Webservices, der indeholder temporaler og udstiller operationerne opret, slet, opdater eller tilsvarende, skal anvende tidspunktet for kaldet som registreringstidspunkt, og registreringstidspunktet kan ikke medsendes af serviceanvender.

MK10	Anvendelse af temporaler i almindelige søgefunktioner
	Webservices, der indeholder temporaler og udstiller operationer til fremsøgning eller tilsvarende, skal understøtte at kunne returnere et øjebliksbillede på et bestemt tidspunkt, hvor gyldighedstidspunkt angives af serviceanvender, og tidspunktet for kaldet anvendes som registreringstidspunkt.

K11	Udstilling af temporaler i historik- og flader
	Webservices, der har behov for dedikerede funktioner for visning af historik og flader, skal anvende følgende nøgleord som søgeparametre: ”GyldigFra” (angiver starttidspunkt for gyldighed). ”GyldigTil” (angiver sluttidspunkt for gyldighed). ”RegistreringFra” (angiver starttidspunkt i et interval i et revisionsspor). ”RegistreringTil” (angiver sluttidspunkt i et interval i et revisionsspor).
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse hvordan søgeparametre udstilles.

Nonfunktionelle krav til REST webservices

Dette afsnit stiller krav til REST webservices for at sikre bedre interoperabilitet. De nonfunktionelle krav til webservices i systemet er opdelt i følgende områder:

Modellering af REST webservices.
Krav til datarepræsentation.
Krav til dokumentation for REST webservices.
Krav til HTTP header information ved requests.
Krav til HTTP header information ved response.
Øvrige krav til REST webservices.

Modellering af REST webservices

Dette afsnit understøtter retningslinjerne beskrevet i [WEBSER].

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

K12	Navngivning af REST ressourcer
	REST ressourcer skal navngives som navneord, og skal navngives, så der ikke kræves (URI) kodning af navnet.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvordan navngivning af URI og operationer i REST webservices foretages.

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

Krav til datarepræsentation

Datarepræsentation omhandler syntaks og semantik af de data, som webservicen udstiller og sikrer, at data overføres på en ensartet måde. Datarepræsentation er beskrevet i [WEBSER] 4.3.

K13	Udstilling af muligheder for datarepræsentation
	Webservices skal i response header deklarere, hvilke datarepræsentationer (f.eks. JSON, XML) de understøtter
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvilke datarepræsentationer der understøttes.

K14	Udstilling af datarepræsentation
	REST ressourcers data skal repræsenteres i JSON eller XML. Webservicen skal returnere i det format, som serviceanvenderen ønsker, hvis det er muligt.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes datarepræsentationer udstilles.

Krav til dokumentation for REST webservices

Krav til dokumentation omhandler, hvorledes REST webservices kan have automatisk genereret og tilgængelig dokumentation. Dokumentationskravene er en udmøntning af [WEBSER] 3.3 og [Bilag 2].

MK13	Dokumentation af REST webservices i systemet
	Webservicedokumentation for REST webservices skal overholde [OpenAPI] specifikationen og præciseringer angivet i [Bilag 1].

MK14	Dokumentationsformat for REST webservices i systemet
	Systemet skal udstille en dokumentationsfil i JSON for REST webservices, som kan gøre det muligt for mennesker og it-systemer at forstå, udforske og navigere mellem udstillede webservices. Dokumentationsfilen udgør en maskinfortolkelig, systematisk, ensartet og struktureret udstilling af metadata om webservices til serviceanvendere.

K15	Dokumentér udstillede REST webservices i systemet
	Dokumentationen for REST webservices skal indeholde metadataelementerne fra den fællesoffentlige dokumentationsramme, jf. [Bilag 4], og udstillede webservices skal opmærkes i henhold til fællesoffentlige emnesystematikker.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvorledes metadataelementer dokumenteres og opmærkes.

Krav til HTTP header information ved requests

REST webservices i systemet skal have en ensartet anvendelse af http metoder, query strings og header information.

MK15	Anvendelse af GET og POST
	HTTP-metoden GET skal anvendes til at tilgå eller fremsøge en ressource eller en kollektion af ressourcer, og systemet returnerer hele ressourcen eller hele kollektionen (eller den fremsøgte del). Dog kan HTTP-metoden POST anvendes i det tilfælde, hvor der skal medsendes parametre, som ikke kan udtrykkes i en query string fx pga. forespørgslens størrelse eller kompleksitet.

MK16	Anvendelse af DELETE
	HTTP-metoden DELETE skal anvendes, når en ressource skal slettes. HTTP-metoden DELETE kan kun slette individuelle ressourcer og anvendes ikke på kollektioner.

For at fremme interoperabiliteten skal REST webservices anvende samme header information på tværs af fællesoffentlige webservices. Systemet skal således overholde kravene i [Bilag 4] samt [Bilag 2].

K16	Anvend standardiserede REST fremsøgningsparametre
	Søgeoperationer skal som minimum inkludere parametre for udvælgelse (query), sortering af resultater, selektion af returnerede attributter for fremsøgte ressourcer, samt om relaterede ressourcer skal returneres. 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”).
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvordan søgeparametre anvendes mest muligt. Ordregiver lægger desuden vægt på, hvilke yderligere parametre, som kan angives.

K17	Anvendelse af HTTP header ved request (forespørgsler)
	Systemets REST webservices skal understøtte, at alle kald indeholder følgende headers: Content-Type, jf. [Bilag 4]. Accept, jf. [Bilag 4]. Content-Encoding, jf. [Bilag 4]. Accept-Encoding, jf. [Bilag 4]. Accept-Language, jf. [Bilag 4]. OIOIDWS headers, jf. [Bilag 4]. Accept: version, jf. [Bilag 4]. X-HTTP-Method-Override, jf. [Bilag 4] If-Match, jf. [Bilag 2].
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvilke HTTP headers som returneres, samt hvilke HTTP headers som anvendes udover de 9 header specificeret i kravet.

Krav til HTTP header information ved response

Headere skal anvendes som beskrevet i [WEBSER] og [Bilag 4]. Response headere skal anvendes ensartet på tværs af webservices.

K18	Anvendelse af HTTP header ved Response
	Systemets REST webservices skal understøtte, at alle kald indeholder følgende headers: Content-Type, jf. [Bilag 4]. Content-Language, jf. [Bilag 4]. X-Total-Count, jf. [Bilag 4]. Link, jf. [Bilag 4]. Retry-After, jf. [Bilag 4]. Last-Modified, jf. [Bilag 4]. Statusline, jf. [Bilag 4]. X-Progress, jf. [Bilag 2].
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvordan HTTP headers som returneres, samt hvilke HTTP headers som anvendes udover de 8 headers specificeret i kravet.

K19	Anvendelse af paginering
	REST webservices, der udstiller store samlinger af data, skal understøtte paginering i forbindelse med den søgning, webservicen understøtter.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvordan paginering udstilles til en serviceanvender, samt hvordan paginering er implementeret i webservicen, herunder anvendelse af sessions.

Øvrige krav til REST webservices

Øvrige krav omhandler de resterende retningslinjer og uddybende bilag, som ikke er beskrevet i de foregående afsnit.

MK17	Sikring af fejlhåndtering ved anvendelse af PUT og POST
	HTTP-metoden PUT skal udstilles ved oprettelse af en ressource, hvor det er serviceanvenderen, der er ansvarlig for forretningsobjektet inklusive at tildele det et unikt ID. HTTP-metoden PUT skal håndtere oprettelse af en ressource eller en hel kollektion af ressourcer. HTTP-metoden PUT overskriver hele ressourcen eller hele kollektionen, hvis den findes i forvejen. HTTP-metoden POST skal anvendes, når en ressource skal oprettes, og det er serviceudbyderen, der er ansvarlig for forretningsobjektet inklusive at tildele det et unikt ID. HTTP-metoden POST overskriver hele ressourcen, hvis den findes i forvejen.

MK18	Sikring af kald ved gentagelser ved delvis opdatering af et helt objekt i REST webservices
	HTTP-metoden PATCH anvendes, når en ressource skal opdateres delvist. Ressourcens data, som ikke er angivet i forespørgslen, bevarer deres eksisterende værdier.¹

K20	REST webservices skal returnere HTTP statuskoder
	En REST webservice skal anvende HTTP statuskoder, jf. sektion 10 af [RFC2616]: 2xx: Success – Statuskoder med 2xx angiver, at kaldet var en succes (blev gennemført). 4xx: Client Error – Statuskoder med 4xx skyldes en fejl, som serviceanvender har ansvaret for. 5xx: Server Error - Statuskoder med 4xx skyldes en fejl, som serviceudbyder har ansvaret for.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse hvilke statuskoder, som anvendes, og hvorledes fejlkoder kan anvendes af serviceanvendere.

Webservices kan udstille CRUD operationer, hvor det bagvedliggende it-system opdateres asynkront. Asynkrone operationer medfører, at data ikke er gemt og accepteret hos den offentlige institution, før det bagvedliggende fagsystem er opdateret. Asynkrone beskeder for webservices er beskrevet i [Bilag 2].

K21	Asynkron opdatering af fagsystemer for REST webservices
	REST webservices, som opdaterer et fagsystem asynkront, skal overholde mønstret beskrevet i [Bilag 2].
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvilke asynkrone meddelelser behandles. Herunder lægger ordregiver særlig vægt på, hvorledes systemet sikrer, at beskeder ikke mistes, og hvorledes webservicen understøtter, at det bagvedliggende it-system er utilgængeligt.

MK19	Kommunikationsprotokol ved REST webservices
	REST webservices skal anvende HTTP som kommunikationsprotokol.

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

MK20	REST webservices skal kun kunne anvende HTTP sikkert ved udstilling af ressourcer.
	Webservices skal returnere specifikke fejlkoder, hvis serviceanvenderen bruger usikker HTTP (dvs. uden kryptering og autentificering) i stedet for automatisk at omstille serviceanvenderen til en sikker HTTP ved anvendelse af TLS 1.1 eller nyere.

K22	REST webservices understøtter OIOIDWS REST profile 1.0
	REST Webservices skal anvende OIOIDWS REST profile 1.0 ved håndtering af data.
	[Tilbudsgivers besvarelse af krav] Ordregiver lægger vægt på, at det fremgår klart og tydeligt af tilbudsgivers besvarelse, hvordan webservices implementerer OIOIDWS, herunder hvorledes identitet overføres og håndhæves af webservicen.

Kilder

ID	Kilde
[BILAG 1]	Bilag 1 ”Dokumentation for REST webservices” til [WEBSER]
[BILAG 2]	Bilag 2 ”Fejlstruktur og fejlkoder for REST webservices” til [WEBSER]
[BILAG 4]	Bilag 4 ” Specifikation for brug af HTTP til REST” til [WEBSER]
[FIELDING]	Roy Fielding (2000) Architectural Styles and the Design of Network-based Software Architectures. Tilgængelig på: https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
[HTTP]	“Hypertext Transfer Protocol (HTTP/1.1)”, RFC 7230, 7231, 7232, 7233, 7234, 7235.
[MODEL]	Digitaliseringsstyrelsen (2017) Fællesoffentlige regler for begrebs- og datamodellering. Tilgængelig på: https://arkitektur.digst.dk/metoder/regler-begrebs-og-datamodellering
[OPENAPI]	Open API Initiative (2017) OpenAPI-Specification. Tilgængelig på: https://github.com/OAI/OpenAPI-Specification
[W3C]	Definition af webservices og relation til REST er angivet i: http://www.w3.org/TR/ws-arch/#relwwwrest
[WEBSER]	Digitaliseringsstyrelsen (2017) Fælles retningslinjer for REST webservices. https://arkitektur.digst.dk/metoder/retningslinjer-webservices
[WS-GLOSS]	W3C web services glossary: http://www.w3.org/TR/ws-gloss/

Fodnoter

¹ Tidligere skal i denne sammenhæng forstås som ”lige før operationen påbegyndes”.

Permanent URL til artiklen: https://arkitektur.digst.dk/node/1166