Bilag 2 - Fejlstruktur og fejlkoder for REST webservices

Body: 

Dette dokument beskriver, hvordan fejl skal håndteres i REST webservices. Dokumentet er bilag 2 til fællesoffentlige retningslinjer for webservices, beskrevet i ”Fælles retningslinjer for REST webservices” [WEBSER] og er en konkretisering af fejlmeddelelse, jf. afsnittet Servicefejlmeddelelser i [WEBSER].

Dokumentet beskriver hvorledes en struktureret fejlmeddelelse på tværs af myndigheders webservices giver større interoperabilitet, idet serviceanvendere af webservices får et mere genkendeligt og homogent it-landskab.

Den strukturerede fejlmeddelelse fastlægger:

  • Anvendelse af fejlstrukturer på tværs af protokoller og integrationsmønstre.
  • Fejlmeddelelse for REST webservices der anvender HTTP ved kald
  • Beskrivelse af serviceudstilleres og serviceanvenderes ansvar
  • Ensartede fejlstrukturer, som definerer syntaks for fejlbeskeder
  • Brug af forståelige fejlbeskeder, der sikrer, at der kan gives forståelige fejlbeskeder til både it-systemer og slutbrugere

Dette dokument beskriver ikke, hvorledes services monitoreres og forvaltes.

Nærværende afsnit indeholder indledning, beskrivelse af målgruppe samt afgrænsninger.

Det følgende afsnit ndeholder retningslinjer for fejlmeddelelse af REST webservices. Her beskrives, hvorledes HTTP statuskoder anvendes og giver konkret indhold af fejlstrukturer, der returneres til serviceanvendere.

Derefter beskrives det konkrete indhold af HTTP headeren ved fejl og anvendelsen af HTTP statuskoder.

Efterfølgende beskrives den generelle fejlstruktur for fejlmeddelelser, som kan sendes på tværs af protokoller, herunder konkrete eksempler i JSON, XML og CSV.

Til sidst angives en liste over anvendte referencer.

Målgruppe

Målgruppen for læsere af dette dokument er:

  • IT-Arkitekter og udviklere for serviceudstillere, som ønsker at udstille en webservice med en fejlmeddelelse, som overholder de fællesoffentlige retningslinjer.
  • IT-Arkitekter og udviklere for serviceanvendere, som ønsker at anvende en webservice med en fejlmeddelelse, som overholder de fællesoffentlige retningslinjer.

Fejlmeddelelser i REST webservices

REST webservices anvender HTTP som kommunikationsprotokol, og indikerer overfor serviceanvendere at en fejl er opstået ved at overføre en statuskode i header. Tilsvarende er det best-practice at medsende en struktureret fejl i body af et HTTP response.

Statuskoder med tilhørende tekst har en værdi inden for et bestemt udfaldsrum, som er angivet i standarden. Statuskoder er en endelig liste defineret i sektion 10 af [RFC2616]. Statuskoder er en liste over både meget konkrete fejlkoder og mere generelle fejlkoder, hvor udfaldsrummet for statuskoder er angivet i RFC 7231, jf. Appendiks A. I REST og HTTP-standarden er det således op til serviceudstiller at afgøre, hvilke applikationsfejl, der modsvarer de enkelte HTTP statuskoder.

For at skabe mere ensartede snitflader for serviceanvendere præciserer retningslinjerne, hvorledes applikationsfejl udstilles.

Serviceanvenderen skal se information i statuskoder i kombination med fejlstrukturer medsendt i body. Fejlstruktur i body giver mulighed for en mere nuanceret fejlbeskrivelse, fx med et fast skema som angiver syntaks og semantik. Fejlstrukturer defineret i skemaer muliggør anvendelse af samme fejlstruktur på tværs af protokoller, fx SOAP eller FTP. Strukturen for fejlmeddelelser er beskrevet yderligere i afsnittet 'Struktur for REST fejlmeddelelse i header'.

Statuskoder er beskrevet af HTTP protokollen, som vedligeholdes af IANA og præciserer anvendelsen, jf. appendiks A. Det er op til serviceudstiller at træffe designbeslutning om, hvilke statuskoder der anvendes til de applikationsfejl, som er mulige i den enkelte service. Den designbeslutning er situationsafhængig og kan være svær at ensrette på tværs af webservices. Retningslinjerne har derfor ikke specifikke retningslinjer for, hvorledes applikationsfejl udstilles.

En REST webservice skal dog altid overholde følgende generelle design til returnering af statuskoder:

  • 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 serviceudstiller har ansvaret for.

Indholdet af tekstfeltet i HTTP-statusfeltet kan anvendes frit af serviceudstiller, men mange services anvender som best-practice standardteksten til den tilhørende fejlkode. Standardteksten er angivet i ”description” kolonnen i Appendiks A. Retningslinjerne vil følge denne metode og angive standardteksten fra IANA. Fejlmeddelelser i body fra webservice skal angives i en fejlstruktur, jf. afsnittet 'Struktur for REST fejlmeddelelse i header'.

Håndtering af fejl i backend-systemer

Det er en udbredt løsning i det offentlige it-landskab, at CRUD operationer sker asynkront. Dette afsnit beskriver, hvorledes serviceanvendere kan få en asynkron kvittering fra et backend-system ved anvendelse af en REST webservice. Der er således både en teknisk kvittering, som er synkron (response/request), og en asynkron forretningskvittering.

Eksempel på brugsscenarie:

Webservicen står i en demilitariseret zone (DMZ) og persisterer data midlertidigt i en kø eller tilsvarende, som efterfølgende loades ind i et backend-system. Her kan webservicen i DMZ kun tjekke syntaks og semantik som angivet i snitfladen, men kan ikke håndtere forretningsregler som håndhæves i backend-systemet. En forretningsregel kan fx være:serviceanvender ønsker at journalisere et dokument på en sag, men sagen findes ikke i backend-systemet, hvilket giver en fejl.”

En del HTTP-metoder har dog ikke et body i response, når det er et succesfuldt synkront kald. Derfor tillader HTTP ikke, at der medsendes en mere detaljeret body om, hvordan status på forretningskvittering fremskaffes. Det gælder følgende metoder:

  • PUT
  • PATCH
  • DELETE

PUT-metoden skal anvendes ved oprettelse og opdatering af en ressource ved angivelse af et id, POST kan oprette en ressource uden et id, jf. [Bilag 4] ” Specifikation for brug af HTTP til REST” til [WEBSER]. Et kald med PUT eller POST til en REST ressource kan umiddelbart have to relevante resultater:

  • Data er modtaget og ressourcen i it-systemet er opdateret. I det tilfælde skal en webservice returnere HTTP statuskode 201 for at kunne overholde retningslinjerne.
  • Data er modtaget og ressourcen i et bagvedliggende it-system (backend-systemet) er ikke opdateret. Webservicen returnerer HTTP-statuskode 202 med en custom header kaldet X-Progress med en URI, hvor status på kaldet efterfølgende kan hentes med en GET request. I GET response fremgår forretningskvitteringen med status på processen.

Såfremt processen resulterer i en efterfølgende fejl fra backend-systemet, er det serviceanvenders ansvar at håndtere fejlen.

Tilsvarende gælder for DELETE, dog returneres HTTP-statuskode 200 ved succes i stedet for HTTP-statuskode 201.

Retningslinjerne omfatter ikke præciseringer for PATCH på dette område.

Struktur for REST fejlmeddelelse i header

Dette afsnit indeholder beskrivelse af udformning af HTTP headers i forbindelse med fejlmeddelelse. Øvrige krav til HTTP headers som operationelle parametre beskrives i [Bilag 4] ” Specifikation for brug af HTTP til REST”.

I det følgende beskrives HTTP headers for HTTP request (kald) og HTTP response (svar) i forskellige afsnit, da der er forskellige krav til brug af headere.

Request headers

Serviceanvenderen skal inkludere HTTP headeren ”Accept-Language” for at angive foretrukket sprog. Såfremt der opstår en fejl i den udstillede service, skal brugervendte fejlmeddelelser være på det angivne sprog, hvis det er muligt. Hvis serviceanvender ikke har angivet sprog, så skal brugervendte fejlmeddelelser returneres på dansk.

Serviceanvendere skal inkludere HTTP headeren ”If-Match” i PUT-metoder, hvis serviceanvender ønsker en fejl fra serviceudstiller, hvis den angivne ressource ikke er ændret, siden den sidst var blevet opdateret af serviceanvender. Det kan forhindre overskrivninger i ressourcer (”race conditions”) ved samtidige opdateringer af hele ressourcer.

Response headers

I tilfælde af en fejl skal REST webservices returnere følgende header felter:

  • ”Last-Modified”: dato for ressourcens sidste opdateringsdato skal returneres ved fejl i PUT-metoder.
  • ”Content-Language”: er en specifikation af sproget i fejlmeddelelsen.
  • Statusline, indeholder statuskode og fejlteksten i formatet: ”HTTP-Version SP Status-Code SP Reason-Phrase CRLF”.

Struktur for fejlmeddelelser i generelle webservices

Strukturen for generelle fejlmeddelelser anvendes mellem webservices på tværs af grænser mellem services, derfor må fejlmeddelelser ikke indeholde interne fejlkoder, fx stacktrace.

Fejlmeddelelsen håndterer både fejl fra et kald, som vedrører en enkelt ressource, eller kald som vedrører en kollektion af ressourcer. Fx hvis en operation opdaterer 100 sager, og der er tre som fejler, så skal der returneres en sigende fejl per sag.

Fejlmeddelelser skal returneres i UTF-8 encoding.

Fejlmeddelelsen skal indeholde følgende:

Feltnavn

Forklaring

Statuskode

Statuskode skal være værdien svarende til HTTP-statuskoden.

Ressource-id

Ressource-id angiver den ressource, som fejlen omhandler. Såfremt der er tale om en generel fejl i webservicen, skal feltet være tomt.

Transaktionsidentifikator

Kaldets transaktionsidentifikator skal medsendes jf. R14 i [WEBSER].

Indkomne registrerede parametre

Webservicens indgående parametre, undtagen evt. binært indhold, skal inkluderes i fejlbeskrivelsen.

Fejlkode

Webservicens fejlkode som svarer til en fejlkode i dokumentationen. Fejlkoden vil typisk være fra en mere detaljeret liste end statuskode.

Systemfejlbeskrivelse,

Teksten skal indeholde så mange relevante detaljer for serviceanvender som muligt, dog under hensyntagen til at undgå store fejlmeddelelser grundet båndbreddeforbrug, samt hensyn til sikkerhedskrav og krav om informationers følsomhed og fortrolighed.

Brugervendt fejlbeskrivelse

Webservicen skal returnere en brugervendt fejlbeskrivelse på et bestemt sprog, som angivet af serviceanvender, eller på dansk, såfremt serviceanvender ikke har angivet et sprog, eller såfremt webservicen ikke returnerer fejlbeskrivelsen på det ønskede sprog.

Link til dokumentation

Link til dokumentation er en http:uri til dokumentation af fejlen.

Eksempel JSON

Nedenstående viser et eksempel på en JSON implementering af den generelle fejlmeddelelse: En REST webservice, som returnerer JSON, skal returnere følgende struktur for at overholde retningslinjerne ved fejl:

  
{ 
     "Status" : ”418”,
     ”Ressourceid” : ”4Ab7b763-8213-4c85-aa2e-bb3106f5227d”
     ”Transactionid” : ” 34b7b763-8213-4c85-aa2e-bb3106f5227d”,
     "Parameters" : [123,456,ABC],
     "ErrorCode" : 444444, 
     ”ErrorDesciption” : ”parameter is not numeric”,
     ”UserDesciption” : ”Værdien ABC er ikke et tal”,
     "MoreInfo" : ”http://www.genstand.com/help/v2/swagger.json” }
   

Eksempel XML

Nedenstående viser et eksempel på en JSON implementering af den generelle fejlmeddelelse: En REST webservice, som returnerer XML, skal returnere følgende struktur for at overholde retningslinjerne ved fejl:

<Errormessage>
     <Status>418</status>
     <”Ressourceid>4Ab7b763-8213-4c85-aa2e-bb3106f5227</Ressouceid>
     <Transactionid>34b7b763-8213-4c85-aa2e-bb3106f5227d</Transactionid>
     <Parameters><Parameter>123</Parameter><Parameter>456</Parameter><Parameter>ABC</Parameter>
     <ErrorCode> 444444 <ErrorCode>
     <ErrorDesciption>parameter is not numeric<ErrorDescription>
     <UserDesciption>Værdien ABC er ikke et tal</UserDesciption>
     <MoreInfo>[CDATA[[http://www.genstand.com/help/v2/swagger.json]]</MoreInfo>

Eksempel CSV(Batch)

Errorline:

     ”418”, 4Ab7b763-8213-4c85-aa2e-bb3106f5227d, ”34b7b763-8213-4c85-aa2e-bb3106f5227d”, ”[123,456,ABC]”, ”444444”, ”parameter is not numeric”, ”Værdien ABC er ikke et tal”, ”http://www.genstand.com/help/v2/swagger.json”

Eksempel Status request JSON

Som beskrevet ovenfor, kan en asynkron service medføre, at en serviceanvender må forespørge en statusservice, som returnerer status for en given asynkron transaktion. En URL angives af service udstiller i header, fx: Get eksempel URL: ”http://www.genstand.com/Geonoegler/status/34b7b763-8213-4c85-aa2e-bb3106...”.

Nedenstående viser et eksempel på en JSON implementering af den request og response for en statusmeddelelse:

GET JSON Request:
     {”Transactionid” : ” 34b7b763-8213-4c85-aa2e-bb3106f5227d”}

En REST webservice, som returnerer XML, skal returnere følgende struktur for at overholde retningslinjerne ved fejl:

GET JSON Response har en status, som har udfaldsrummet Accepted, OK, Failed:
     {”Transactionid” : ” 34b7b763-8213-4c85-aa2e-bb3106f5227d”, ”Pro-gress”: ”Accepted” ”Retry-After”: ”1000”}
     {”Transactionid” : ” 34b7b763-8213-4c85-aa2e-bb3106f5227d”, ”Pro-gress”: ”OK” }
     {”Transactionid” : ” 34b7b763-8213-4c85-aa2e-bb3106f5227d”, 
     ”Progress”: ”Failed”,  
     "Status" : ”418”,
     ”Transactionid” : ” 34b7b763-8213-4c85-aa2e-bb3106f5227d”,
     "Parameters" : [123,456,ABC],
     "ErrorCode" : 444444, 
     ”ErrorDesciption” : ”parameter is not numeric”,
     ”UserDesciption” : ”Værdien ABC er ikke et tal”,
     "MoreInfo" : ”http://www.genstand.com/help/v2/swagger.json” 
     }

Kilder

ID

Kilde

[BILAG 1]

Bilag 1 ”Dokumentation for REST webservices” til [WEBSER]

[BILAG 3]

Bilag 3 ”Nonfunktionelle krav til realisering af retningslinjer”

[BILAG 4]

Bilag 4 ” Specifikation for brug af HTTP til REST” til [WEBSER]

[WEBSER]

Digitaliseringsstyrelsen (2017) Fælles retningslinjer for REST webservices”. Tilgængelig på: https://arkitektur.digst.dk/metoder/retningslinjer-webservices

[HTTP]

Hypertext Transfer Protocol (HTTP/1.1), RFC 7230, 7231, 7232, 7233, 7234, 7235.

[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

[RFC2616]

RFC 2616 https://www.ietf.org/rfc/rfc2616.txt

Appendiks A. - HTTP Status koder

Listen over HTTP-statuskoder vedligeholdes af IANA og er per oktober 2017:

Tabel 1 Liste over HTTP-statuskoder

Value

Description

Reference

100

Continue

[RFC7231, Section 6.2.1]

101

Switching Protocols

[RFC7231, Section 6.2.2]

102

Processing

[RFC2518]

103-199

Unassigned

 

200

OK

[RFC7231, Section 6.3.1]

201

Created

[RFC7231, Section 6.3.2]

202

Accepted

[RFC7231, Section 6.3.3]

203

Non-Authoritative Information

[RFC7231, Section 6.3.4]

204

No Content

[RFC7231, Section 6.3.5]

205

Reset Content

[RFC7231, Section 6.3.6]

206

Partial Content

[RFC7233, Section 4.1]

207

Multi-Status

[RFC4918]

208

Already Reported

[RFC5842]

209-225

Unassigned

 

226

IM Used

[RFC3229]

227-299

Unassigned

 

300

Multiple Choices

[RFC7231, Section 6.4.1]

301

Moved Permanently

[RFC7231, Section 6.4.2]

302

Found

[RFC7231, Section 6.4.3]

303

See Other

[RFC7231, Section 6.4.4]

304

Not Modified

[RFC7232, Section 4.1]

305

Use Proxy

[RFC7231, Section 6.4.5]

306

(Unused)

[RFC7231, Section 6.4.6]

307

Temporary Redirect

[RFC7231, Section 6.4.7]

308

Permanent Redirect

[RFC7538]

309-399

Unassigned

 

400

Bad Request

[RFC7231, Section 6.5.1]

401

Unauthorized

[RFC7235, Section 3.1]

402

Payment Required

[RFC7231, Section 6.5.2]

403

Forbidden

[RFC7231, Section 6.5.3]

404

Not Found

[RFC7231, Section 6.5.4]

405

Method Not Allowed

[RFC7231, Section 6.5.5]

406

Not Acceptable

[RFC7231, Section 6.5.6]

407

Proxy Authentication Required

[RFC7235, Section 3.2]

408

Request Timeout

[RFC7231, Section 6.5.7]

409

Conflict

[RFC7231, Section 6.5.8]

410

Gone

[RFC7231, Section 6.5.9]

411

Length Required

[RFC7231, Section 6.5.10]

412

Precondition Failed

[RFC7232, Section 4.2] [RFC8144, Section 3.2]

413

Payload Too Large

[RFC7231, Section 6.5.11]

414

URI Too Long

[RFC7231, Section 6.5.12]

415

Unsupported Media Type

[RFC7231, Section 6.5.13] [RFC7694, Section 3]

416

Range Not Satisfiable

[RFC7233, Section 4.4]

417

Expectation Failed

[RFC7231, Section 6.5.14]

418-420

Unassigned

 

421

Misdirected Request

[RFC7540, Section 9.1.2]

422

Unprocessable Entity

[RFC4918]

423

Locked

[RFC4918]

424

Failed Dependency

[RFC4918]

425

Unassigned

 

426

Upgrade Required

[RFC7231, Section 6.5.15]

427

Unassigned

 

428

Precondition Required

[RFC6585]

429

Too Many Requests

[RFC6585]

430

Unassigned

 

431

Request Header Fields Too Large

[RFC6585]

432-450

Unassigned

 

451

Unavailable For Legal Reasons

[RFC7725]

452-499

Unassigned

 

500

Internal Server Error

[RFC7231, Section 6.6.1]

501

Not Implemented

[RFC7231, Section 6.6.2]

502

Bad Gateway

[RFC7231, Section 6.6.3]

503

Service Unavailable

[RFC7231, Section 6.6.4]

504

Gateway Timeout

[RFC7231, Section 6.6.5]

505

HTTP Version Not Supported

[RFC7231, Section 6.6.6]

506

Variant Also Negotiates

[RFC2295]

507

Insufficient Storage

[RFC4918]

508

Loop Detected

[RFC5842]

509

Unassigned

 

510

Not Extended

[RFC2774]

511

Network Authentication Required

[RFC6585]

512-599

Unassigned