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. Afsnit 2 i hoveddokumentet beskriver 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.

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

Afsnit 2, 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å.

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

Afsnit 4, 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, jf. afsnit 3. 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, jf. afsnit 3.1.
  • Krav til webservicedokumentation, jf. afsnit 3.2.
  • Krav til versionering, jf. afsnit 3.3.
  • Krav til logning og monitorering, jf. afsnit 3.4.
  • Krav til udformning af fejlmeddelelser, jf. afsnit 3.5.
  • Krav til datarepræsentation, jf. afsnit 3.6.

Generelle krav til udstilling af webservices

De generelle krav til arkitektur understøtter retningslinjerne beskrevet i [WEBSER] afsnit 3.1 og 3.2.

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] afsnit 3.3 og [Bilag 1] til [WEBSER]. For REST webservices henvises også til afsnit 4.3.

K5

Dokumentér udstillede webservices i systemet

 

Dokumentationen for webservices skal indeholde metadataelementerne fra den fællesoffentlige dokumentationsramme, jf. [Bilag 1] afsnit 3.2. 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] afsnit 3.4. 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 og juridiske krav til logning er ikke færdig analyseret i version 0.8. Dette afsnit er derfor ikke endeligt.]

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] afsnit 3.7, samt i [Bilag 2] afsnit 4.

K10

Anvend fejlstruktur ved fejlbeskeder i systemets webservices

 

Fejlmeddelelsen skal overholde struktur for fejlmeddelelser som beskrevet i [WEBSER] afsnit 3.7, samt i [Bilag 2] afsnit 4.

[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] afsnit 3.8. Der kan være behov for at angive forskellige tidsmæssige aspekter af en ressource – såkaldte temporaler – i en webservice, jf. [WEBSER] afsnit 3.8. 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, jf. afsnit 4.1.
  • Krav til datarepræsentation, jf. afsnit 4.2.
  • Krav til dokumentation for REST webservices, jf. afsnit 4.3.
  • Krav til HTTP header information ved requests, jf. afsnit 4.4.
  • Krav til HTTP header information ved response, jf. afsnit 4.5.
  • Øvrige krav til REST webservices, jf. afsnit 4.6.

Modellering af REST webservices

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

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] afsnit 3.2, 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] afsnit 2.2 samt [Bilag 2] afsnit 3.1.

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] 4 afsnit 2.2.1.
  • Accept, jf. [Bilag 4] 4 afsnit 2.2.2.
  • Content-Encoding, jf. [Bilag 4] 4 afsnit 2.2.3.
  • Accept-Encoding, jf. [Bilag 4] 4 afsnit 2.2.4.
  • Accept-Language, jf. [Bilag 4] 4 afsnit 2.2.5.
  • OIOIDWS headers, jf. [Bilag 4] 4 afsnit 2.2.6.
  • Accept: version, jf. [Bilag 4] 4 afsnit 2.2.7.
  • X-HTTP-Method-Override, jf. [Bilag 4] 4 afsnit 2.2.8
  • 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] afsnit 4 og [Bilag 4] afsnit 3.7. 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] 4 afsnit 2.3.1.
  • Content-Language, jf. [Bilag 4] 4 afsnit 2.3.2.
  • X-Total-Count, jf. [Bilag 4] 4 afsnit 2.3.3.
  • Link, jf. [Bilag 4] 4 afsnit 2.3.4.
  • Retry-After, jf. [Bilag 4] 4 afsnit 2.3.5.
  • Last-Modified, jf. [Bilag 4] 4 afsnit 2.3.6.
  • Statusline, jf. [Bilag 4] 4 jf. afsnit 2.3.7.
  • X-Progress, jf. [Bilag 2] 2 afsnit 2.1.

[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 afsnit 4.1 til 4.5.

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

 

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] afsnit 2.1.

K21

Asynkron opdatering af fagsystemer for REST webservices

 

REST webservices, som opdaterer et fagsystem asynkront, skal overholde mønstret beskrevet i [Bilag 2] afsnit 2.1.

[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, version 1.0.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, version 0.98.

https://arkitektur.digst.dk/metoder/retningslinjer-webservices

 

[WS-GLOSS]

W3C web services glossary: http://www.w3.org/TR/ws-gloss/

Fodnoter

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