Bilag 1 - Dokumentation for REST webservices

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. Rollerne¹ 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	MÅ	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	MÅ	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	MÅ	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	MÅ	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	MÅ	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

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

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