Bilag 1 - Dokumentation for REST webservices

Body: 

Fælles rammeværk til dokumentation af REST webservices

Dette dokument beskriver elementer, der indgår i dokumentation af REST webservices. Dokumentet er et bilag til de fællesoffentlige retningslinjer for webservices, beskrevet i ”Fælles retningslinjer for REST webservices” [WEBSER].

Serviceudbydere udstiller data og funktionalitet og skal dokumentere deres webservices som en implikation af retningslinje R06 ”Dokumentér udstillede webservices i overensstemmelse med den fællesoffentlige dokumentationsramme for webservice”.

Serviceanvendere er modtagere af dokumentationen og kan overordnet set være brugere i form af mennesker og it-systemer. Dokumentation af REST webservices skal derfor kunne læses og fortolkes af både mennesker og it-systemer.

Det følgende afsnit indeholder en begrundelse for valget af en profileret anvendelse af OpenAPI specifikation (se [OPENAPI]) som det fælles rammeværk for REST dokumentation.

’Skema for dokumentation af REST webservices’ profilerer anvendelsen af OpenAPI specifikationen. Skemaet specificerer de konkrete elementer i rammeværket, der skal indgå i dokumentationen.

OpenAPI er det fælles rammeværk

OpenAPI realiserer retningslinje R06 i [WEBSER] for webservices ved at understøtte behovet for tilvejebringelse af et standardiseret rammeværk for dokumentation af webservices. Rammeværket anviser serviceudbyderne, hvilke metadataelementer der skal dokumenteres og serviceudbydere skal udtille REST webservices i en dokumentationsfil for hver version af deres webservice.

Flere kilder til et fælles rammeværk til dokumentation af REST webservices kan findes som best-practice i eksempelvis modne samlinger af webservices eller som eksisterende specifikationer for dokumentation. Eksempler på best-practice er Amazon AWS, Confluence og Fællesoffenlige Grunddata, der har dokumentation, hvor en række fælles træk går igen.

Dokumentation kan udtry kkes i eksisterende specifikationer for dokumentation, hvor de mest udbredte er OpenAPI (Swagger), RAML og SmartAPI, hvor disse specifikationer anbefaler bestemt klassifikation af dokumentationselementer.

Best practices og specifikationer er dog forskellige i deres tilgange til dokumentation og anvendelse af metadataelementer hertil. Det er en udfordring, men begge kan hver især give værdi for serviceudbydere, som skal producere og udstille dokumentation af webservices. Det er dog af væsentlig betydning, at dokumentationen gøres ensartet for at øge interoperabiliteten. Realisering af R06 ”Et fælles rammeværk for dokumentation” medfører derfor et aktivt valg imellem de forskellige mulige kilder og specifikationer hertil.

OpenAPI vurderes at være den mest udbredte specifikation og understøtter de dokumentationselementer, som er relevante for retningslinjerne. OpenAPI specifikationen er dermed valgt for at danne grundlag for det fælles rammeværk jf. [OPENAPI].

Valget af OpenAPI er begrundet ud fra, at OpenAPI specifikationen kan sikre, at:

  • Serviceanvendernes dokumentationsbehov kan dækkes.
  • Serviceudbyderne understøttes i tilvejebringelse af dokumentationen.

De to ovenstående argumenter underbygges i de to følgende afsnit.

OpenAPI dækker serviceanvenderes dokumentationsbehov

Serviceanvenderne er modtagere af dokumentationen. OpenAPI tilbyder dækning af de forskellige dokumentationsbehov, som serviceanvenderne har i forhold til:

  • Roller hos serviceanvenderne.
  • Typer af dokumentation.

Disse beskrives kort i det følgende.

Roller hos serviceanvenderne

Serviceanvendere kan overordnet set være brugere i form af mennesker eller it-systemer, der begge har behov for, at webservicen kan fremsøges, forstås og udforskes.

Med OpenAPI dokumentationsfilen kan der tilvejebringes dokumentation, som tilgodeser dokumentationsbehovet hos serviceanvendernes forskellige menneskelige roller i relation til anvendelse af webservices. Rollerne hos serviceanvendere omfatter bl.a. en enterprise arkitekt, en udvikler, og en service manager. Rollerne1 har forskellige behov i forhold til dokumentation af REST webservices: 

  • Serviceanvender i rollen som enterprise arkitekt har ansvar for de anvendte webservices’ match med de forretningsmæssige behov, og hvordan webservices kan anvendes til at skabe sammenhængende løsninger og give værdi til forretningen. Enterprise arkitekten skal med dokumentationen kunne forstå webservicen og dens interoperabilitet i forhold til serviceanvendernes egne løsninger og webservices.
  • Serviceanvender i rollen som udvikler har ansvar for den konkrete tekniske ibrugtagning af de anvendte webservices. Udvikleren skal med dokumentationen kunne læse webservicens logiske funktionalitet, samt hvorledes webservicen programmatisk anvendes. I forbindelse med udviklers anvendelse af dokumentation af webservices, er det efterspurgt og ønskeligt, at kodeeksempler og anvendte eksempler indgår.
  • Serviceanvenderen i rollen som servicemanager har ansvar for driften af systemlandskabet i serviceanvenderens organisation. Servicemanageren er interesseret i, hvordan anvendte webservices driftsafvikles, og hvordan de påvirker driften af det øvrige systemlandskab. Servicemanageren skal med dokumentationen for anvendte webservices kende den kvalitet, de anvendte webservices driftsafvikles med, fx i form af et dokumenteret Service Level Agreement (SLA).

Typer af dokumentation

Brug af OpenAPI understøtter serviceanvendernes behov for forskellige typer af dokumentation:

  • Grundlæggende dokumentation af REST webservices, målrettet den overordnede forståelse, det kan fx være:
    • Ejerskab, oppetider, forretningsområde, vilkår for anvendelse og typiske brugsscenarier.
    • Angivelse af metadataelementer i dokumentationsfilen.
  • Semantisk dokumentation, målrettet specifik forståelse af udstillede data, fx:
    • Bagvedliggende modeller og beskrivelse af data og datasamlinger, man kan tilgå via webservices.
    • Semantisk dokumentation beskrives i dokumentationsfilen ved angivelse af metadataelementer fra de relevante afsnit.
  • Syntaktisk dokumentation, målrettet serialisering og korrekt indlæsning af repræsentationen af data og datatyper, fx:
    • XML/JSON skemaer og eksempler på forespørgsel og svar i forbindelse med anvendelse af webservices.
    • Syntaktisk dokumentation beskrives i dokumentationsfilen ved angivelse af de krævede metadataelementer.
  • Udviklerdokumentationen, målrettet den konkrete tekniske ibrugtagning og anvendelse af udstillede webservices. Gerne illustreret med konkrete eksempler, fx:
    • Kodeeksempler og anvendereksempler.
    • Udviklerdokumentation beskrives i dokumentationsfilen ved angivelse af metadataelementer fra alle underafsnit.
  • Sikkerhedsdokumentation, i form af webservices understøttede sikkerhedsmekanismer skal sikre, at serviceanvendere forstår hvilke sikkerhedsmekanismer de skal anvende for at tilgå webservices, fx:
    • OIO-IDWS og eventuelt andre supplerende metoder.
    • Sikkerhedsdokumentation beskrives i dokumentationsfilen ved angivelse af de relevante metadataelementer.
  • Driftsdokumentation, som muliggør, at serviceanvendere kan basere deres egen drift på tilgængelighed af de anvendte webservices, fx:
    • Webservices’ realiserede oppetid og kontaktinformation til serviceudbyderen, der fx kan anvendes i forbindelse med driftsspørgsmål eller webservicenedbrud.
    • Driftsdokumentation beskrives i dokumentationsfilen ved angivelse af metadataelementer fra skemaet

OpenAPI understøtter serviceudbyderne i tilvejebringelse af dokumentation

Serviceudbydere i det fællesoffentlige it-landskab skal, som en implikation af retningslinjerne, tilvejebringe dokumentation af deres udstillede webservices.

OpenAPI specifikationen understøtter serviceudbyderne i tilvejebringelse af dokumentation via:

  • God værktøjsunderstøttelse, fx Swagger [SWAGGER].
  • Moden, udbredt og afprøvet specifikation.
  • God dækning på metadataelementer og mulighed for at udvide med ekstra metadatalementer.
  • God dækning i forhold til forskellige udviklingssprog (relevant for produktion af dokumentationsfilen).
  • En velafprøvet kilde for det fælles skema for dokumentation af REST webservices og klare anvisninger på indhold og struktur af dokumentationsfilen.

Skema for dokumentation af REST webservices

Dette afsnit beskriver et skema for dokumentation af REST webservices og er en profilering af OpenAPI 3.1 til dansk fællesoffentlig anvendelse. Først beskrives, hvordan serviceudbyderne på den baggrund skal producere og udstille en dokumentationsfil.

Afsnittet beskriver og præciserer de udvalgte OpenAPI elementer, der SKAL, BØR, eller KAN indgå i den dokumentationsfil, som serviceudbydere af REST webservices skal producere og udstille.

Detaljerne i OpenAPI 3.1 specifikationen er tilgængelige her: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#documentStructure

Skemaet for dokumentationsindhold er angivet i skemaet for dokumentation.

Skemaet er udformet som en profilering for anvendelse af en række specifikke metadataelementer i OpenAPI dokumentationsfilen.

Skemaet skal anvendes sammen med OpenAPI specifikationen i forhold til at tilvejebringe dokumentationsfilen.

Serviceudbydere skal producere og udstille en dokumentationsfil

Med brug af OpenAPI specifikationen og det fælles skemas præcisering skal serviceudbydere producere og udstille en dokumentationsfil, som kan gøre det muligt for mennesker og it-systemer at forstå, udforske og navigere imellem udstillede webservices.

Dokumentationsfilen udgør en maskinfortolkelig, systematisk, ensartet og struktureret udstilling af metadata om webservices til serviceanvendere.

Dokumentationsfilen skal som minimum udstilles i JSON version.

Dokumentationsfilen navngives openapi.json og udstilles relativt til webservicens baseURI med angivelse af /sprogkode jf. ISO 639-1 for dokumentationsfilens sprog og /openapi.json, fx:

https://matrikler.data.gov.dk/da/openapi.json

Skema for metadataelementer i dokumentationsfilen

Metadataelementerne organiseres i kategorier, som modsvarer behovene for de forskellige typer af dokumentation fra afsnittet vedrørende Typer af dokumentation:

I tabellen nedenfor er vist, hvordan metadataelementerne er defineret, beskrevet og mappet til det relevante OpenAPI element:

Navn

Definition

Datatype

Anbefaling

OpenAPI mapning

[Det foreslåede danske navn på Metadataelementet]

[En beskrivelse af elementets værdi/betydning]

[Datatype]

[SKAL, BØR, KAN]

OpenAPI element

Udvidelse med SmartAPI metadataelementer

For en række af metadataelementerne gælder, at der ikke findes et dækkende element i OpenAPI. I de tilfælde er inddraget metadataelement fra SmartAPI, som anviser en udvidelse af specifikationen for at kunne rumme de nødvendige metadataelementer. SmartAPI bygger på OpenAPI og udvider OpenAPI specifikationen.

SmartAPI metadataelementer angives jf. OpenAPI specifikationens fremgangsmåde for udvidelser med ”x-” foran det pågældende elementer. OpenAPI-filen er dermed stadig valid.

Grundlæggende webserviceinformationer

Følgende tabel viser en oversigt over metadataelementer i den grundlæggende dokumentation af en webservice og af webservicens driftsafvikling.

Metadataelement Beskrivelse Type Anbefaling OpenAPI mapning

OpenAPI version

En angivelse af versionsnummer for OpenAPI-specifikation som ligger til grund for dokumentationsfilen

Tekst SKAL

OpenAPI/

openapi

Webservice Navn Et kort navn på webservicen Tekst SKAL

Info Object/

title

Beskrivelse

En tekstuel og menneskeligt læsbar beskrivelse af webservicens indhold og formål

Tekst SKAL

Info Object/

description

Version Webservicens version. Angives med semantisk versionering Tekst SKAL

Info Object/

version

(anvendes ikke i OpenAPI betydning som version af openapi-fil)

”version” elementet anvendes i SmartAPI betydningen som version for webservice angivet med semantisk versionering.

Base URI

Webservicens grundlæggende URI der tjener som basis for alle ressourcer.

Fx https://data.gov.dk

URI SKAL

Server Object/

url

Anvendelsesvilkår

En URL som linker til en beskrivelse af anvendelsesvilkår for servicen. URI BØR

Info Object/

termsOfService

Adgangsbegrænsninger Indikation af om der er restriktioner på anvendelse af webservicen Tekst

SmartAPI element:

x-accessRestriction

Klassifikation Indikation af hvilke typer data som udstilles af servicen fx FORM koder eller KLE numre. Tekst BØR

SmartAPI element:

x-klassifikation

Næste Major version Er serviceudstillers indikation af hvornår næste breaking change er planlagt til. Såfremt tidspunktet ikke kendes af serviceudstiller, så skal feltet ikke angives. Tekst BØR

SmartAPI element:

x-nextmajorversion

Kontaktnavn Navn på person eller organisatorisk enhed som kan kontaktes angående webservicen. Tekst/URI SKAL

Contact Object

/name

Kontaktinformation URL der peger på kontaktinformation for webservicen. URI SKAL

Contact Object

/url

Kontakt Email Emailadresse for kontaktperson/organisation. Tekst SKAL

Contact Object

/email

API Metadata format

Format for API specifikation.

Tekst

OpenAPI Object

/openapi

Eksterne dokumenter

Link til eksterne dokumenter som beskriver servicen.

Det kan fx være testdrejebøger, som kan hjælpe serviceanvendere med ibrugtagning af webservicen.

External Documentation Object BØR

OpenAPI Object

/externalDocs

Drifts-dokumentation Link til eksterne dokumenter/sider som beskriver status for drift på webservicen. External Documentation Object BØR

OpenAPI Object

/externalDocs

Ressourcer og verber

Følgende tabel viser en oversigt over metadataelementer til dokumentation af webservicens udstillede REST ressourcer.

Metadataelement

Beskrivelse

Type

Anbefaling

OpenAPI mapning

Ressourcesti

En ressource beskrives relativt i forhold til webservicens base URI.

Fx for en ressource ”Sager”: /Sager

URI

SKAL

Path Object

udtrykt ved den relative URI (”/{path}”)

Ressourcebeskrivelse

En tekstuel, menneskeligt læsbar beskrivelse af ressourcen.

Kan eventuelt indeholde eksempler.

Tekst

BØR

Path Item Object

/description

Ressourceverber (HTTP metoder)

Liste og definition af de verber (HTTP metoder) som kan anvendes på ressourcen.

Definition og anvendelse af HTTP metoder skal holde sig inden for de fælles rammer angivet i [Bilag 4] ” Specifikation for brug af HTTP til REST”.

HTTP metoderne udtrykkes relativt i forhold til den udstillede ressource, de arbejder på.

Tekst

SKAL

Path Item Object

/ efterfulgt af angivelse af verbe, fx GET

Parametre

Parametre som gælder for hele den pågældende ressource.

Parametre for specifikke operationer dokumentereres i forbindelse med operationen.

Tekst

BØR

Path Item Object

/parameters

Operationer

Operationer tilgår og manipulerer udstillede ressourcer igennem brug af verber (HTTP metoder) og parametre. En unik operation dannes af ressourcesti (navneord) + HTTP metode (verbum) + anvendte parametre. Følgende tabel viser en oversigt over metadataelementer til dokumentation af webservicens operationer.

Metadataelement

Beskrivelse

Type

Anbefaling

OpenAPI mapning

OperationID

En streng som identificerer operationen unikt og kan anvendes af maskiner.

ID skal være unikt for alle operationer inden for den pågældende webservice.

Tekst

SKAL

Operation Object

/operationId

Operationsbeskrivelse

En tekstuel, menneskelig læsbar beskrivelse af operationens adfærd.

Kan eventuelt indeholde eksempler på operationer.

Tekst

SKAL

Operation Object

/description

Operationsdokumentation

Eksterne dokumenter som beskriver operationens adfærd yderligere

URI

Operation Object

/externalDocs

Operationsparametre

Liste over parametre som gælder for den pågældende operation.

Parametre dokumenteres som beskrevet i det relevante afsnit

Tekst

Operation Object

/parameters

Operationssvar

Liste over mulige svar der returneres fra eksekveringen af en operation.

Tekst

SKAL

Operation Object

/responses

Operationssikkerhed

Angivelse af de muligheder for sikkerhed, som er mulige for den pågældende operation. Anvendes kun, hvis der er afvigelser fra sikkerhed defineret på webservice-niveau.

Tekst

KAN

Operation Object

/security

Parametre

Brug af parametre giver en finere granularitet i operationer, end der kan udtrykkes i den rene kombination af ressource og verbum. Dokumentationen skal indeholde elementer, der beskriver, hvordan parametre anvendes i webservicen og dens operationer. Følgende tabel viser en oversigt over metadataelementerne i dokumentation af webservicens parametre.

Metadataelement

Beskrivelse

Type

Anbefaling

OpenAPI mapning

Parameternavn

En tekstuel, menneskeligt læsbar angivelse af parameterens navn.

Parameter navn skal modsvare Parameter Lokation, så eksempelvis lokation = header modsvares af valid HTTP header parameter.

Tekst

SKAL

Parameter Object

/name

Parameterbeskrivelse

En tekstuel, menneskeligt læsbar beskrivelse af parameteren.

Kan eventuelt indeholde eksempler på brug af parametre.

Tekst

BØR

Parameter Object

/description

Parameterlokation

En angivelse af parameterens lokation:

  • query
  • header
  • URI
  • cookie

Lokation og Parametertitel udgør tilsammen den unikke parameter.

Tekst

SKAL

Parameter Object

/in

Parameter-style

Dokumentation af parameter-style for parameter input og serialisering.

(fx matrix, header, query, template, plain)

Tekst

Parameter Object

/style

Forespørgsel

Forespørgsel anvendes ved operationer, som opdaterer en ressource (svarende til HTTP metoden PUT). Hvis der eksempelvis skal oprettes en ressource (ved brug af HTTP PUT), indeholder forespørgslens body typisk en repræsentation af ressourcen, der skal oprettes. Følgende tabel viser en oversigt over metadataelementerne til dokumentation af indholdet af forespørgsler til opdatering.

Metadataelement

Beskrivelse

Type

Anbefaling

OpenAPI mapning

Forespørgselsbeskrivelse

En tekstuel, menneskelig læsbar beskrivelse af Request Body.

Kan eventuelt indeholde eksempler på Request Bodies.

Tekst

BØR

Request Body Object

/description

Forespørgselsformat

De anvendte repræsentationsformater for data i request body. Fx JSON eller XML

Tekst

SKAL

Request Body Object

/content

Forespørgsels-schema

Skema for request body. Kan beskrives direkte eller ved angivelse af reference. Media type object er defineret i RFC 6838.

schema

SKAL

Media Type Object

/schema

Obligatorisk

Bestemmer om Request Body er er påkrævet i en forespørgsel.

Anbefalet default værdi = false

boolean

BØR

Request Body Object

/required

Retur

Følgende tabel viser en oversigt over metadataelementerne til dokumentation af de svar, der kan forventes på de enkelte webservice operationer. Brug af HTTP statuskoder i svar fremgår af [Bilag 2] ”Fejlstruktur og fejlkoder for REST Webservices”.

Metadataelement

Beskrivelse

Type

Anbefaling

OpenAPI mapning

Returbeskrivelse

En tekstuel, menneskelig læsbar beskrivelse af Operation Response (forespørgsler).

Kan eventuelt indeholde eksempler på Request Bodies.

Tekst

SKAL

Respone Object

/description

Retur Header

Information om enhver header som sendes med i et response på en operation.

Tekst

BØR

Response Object

/headers

Returkode

Den forventede (HTTP-) statuskode for en given operation.

Returkoder for retningslinjerne er defineret i [Bilag 2] ”Fejlstruktur og fejlkoder for REST Webservices”.

Integer

SKAL

Responses Object

/http Status Code

Returformat sepræsentation

En liste af datarepræsentationer som returneres for den givne operationer, fx ”application/json”.

Tekst

SKAL

Response Object

/content

Retur-schema

Et skema som beskriver syntaks og elementer for returformat. Kan enten defineres direkte eller angives via reference til et schema. Media type object er defineret i RFC 6838.

schema

SKAL

Mediatype Object

/schema

Schema for ressourcer

En REST ressource er en abstraktion over information, som kan tilgås via REST webservicen. Intern eller ekstern referencer på schema for datarepræsentationer i response body skal angives i dokumentationen. Følgende tabel viser en oversigt over metadataelementerne til dokumentation af ressourcens schema, henholdsvis datarepræsentation.

Metadataelement

Beskrivelse

Type

Anbefaling

OpenAPI mapning

Schema2

Schema definerer syntaks og termer for webservicens datarepræsentationer i forhold til request og response.

Et schema kan defineres for webservicen og refereres til til ekstern lokation.

Schema

SKAL

Schema Object

Datarepræsentation

Beskrives som en mediaType, fx application/json eller application/xml.

Tekst

SKAL

Responses/

content

Sikkerhed

Metadataelementer til dokumentation af webservicens understøttede sikkerhed gældende for henholdsvis hele webservicen og enkelte metoder.

  • Retningslinjerne angiver OIO IDWS som sikkerhedsmekanisme.
  • Hvis webservicen også understøtter andre sikkerhedsmekanismer, angives det også her.

Følgende tabel viser en oversigt over metadataelementerne til dokumentation af webservices’ sikkerhed:

Metadataelement

Beskrivelse

Type

Anbefaling

OpenAPI mapning

Sikkerhedstype

Udspecificering af webservicens understøttede sikkerhedsmekanismer.

Kan anvendes til også at beskrive, hvis webservicen anvender andre sikkerhedsmekanismer end OIO IDWS, fx til ikke-følsomme data eller lignende.

Tekst

SKAL

Security Scheme Object

/type

Sikkerhedsbeskrivelse

En tekstuel, menneskelig læsbar beskrivelse af understøttet sikkerhed på webservicen.

Tekst

SKAL

Security Scheme Object

/description

Kilder

ID

Kilde

[BILAG 2]

Bilag 2 ”Fejlstruktur og fejlkoder 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]

[OPENAPI]

Open API Initiative (2017) OpenAPI-Specification. Tilgængelig på: https://github.com/OAI/OpenAPI-Specification

[RAML]

RAML Workgroup (2017) RAML. Tilgængelig på: https://raml.org

[WADL]

Marc Wadley (2009) Web Application Description Language. Tilgængelig på: https://www.w3.org/Submission/wadl/

[SmartAPI]

API Interoperability working group (2017) SmartAPI Project. Tilgængelig på: http://smart-api.info

[WEBSER]

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

 

[RFC6570]

RFC6570 URI Template

[SWAGGER]

Swagger. Tilgængelig på: https://swagger.io

[MODENHED]

Fowler (2010) Richardson Maturity Model. Tilgængelig på: https://martinfowler.com/articles/richardsonMaturityModel.html

Fodnoter

1 Bemærk at rollerne findes uanset sourcingstrategien for serviceanvenderens it-løsninger, fx selvom udvikling af en serviceanvenders løsninger sker via en ekstern leverandør.

2 Schema rummer ikke semantisk annotation. Men her kan man overveje at anvende fx JSON-LD eller SAWSDL for at angive koblingen til den semantiske model.