Opdateringer i Webservice 2.0
Ny Protokol
Webservice 1.0 brugte en implementering af en SOAP protokol, hvor hver webservice har været defineret i WSDL/XSD. WSAPI er REST API baseret, hvor webservices er designet i JSON. Som del af den nye protokol er WSAPI yderligere sikret mod uautoriseret adgang ved hjælp af JSON-web-tokens (JWT) samt brugerstyring. Dette betyder at fremadrettet skal dataleverandører oprettes i det interne system, før de kan indberette data. RKKP vil i fremtiden afholde disse møder med de enkelte leverandører, og certificere de enkelte brugere til brugen af Webservice 2.0.
Version kontrol
For at sikre optimal kompatibilitet for dataleverandører vil hver klinisk kvalitetsdatabases webservice understøtte flere versioner/instanser, hvilket giver frihed ift. opdatering af webservices.
JSON-web-token (JWT)
Før afsendelse skal dataleverandører forespørge serveren om en JWT, som fungerer som adgangsbevis efter login. Ved afsendelser af data til RKKP vil man i headeren sende sin JWT med, og derigennem autorisere sin adgang til systemet. Et eksempel på det er:
header={"Authorization": "bearer <access_token>"}
Server respons format
Serverens svar på anmodninger er blevet standardiseret, og vil altid komme i det samme format:
{
"timestamp": "2023-01-01 12:00:00.000000",
"status_code": xxx,
"error_message": "Fejlbesked",
"data": {"Valgfri data": "abc"}
}
JWT-login flow:
For at få en JWT-token skal du følge disse trin:
- Lav en [POST]-request til {url}/auth/login
- 2. I requesten tilføjer i en JSON struktur med {"email": "abc@xx.dk" og "password": "abc"}
- Serveren vil returnere JWT-tokenet i svaret
Server Respons Koder
200: Login success.
400: Forkert email/kodeord.
JWT-refresh flow
Der vil til tider være brug for at forny sin JWT. Det kan gøres ved at gøre følgende:
- Lav en [POST]-request til {url}/auth/refresh som indeholder RAW JSON {"refresh_token": <dit_token>}.
- Serveren vil verificere oplysningerne.
- Ved succes vil serveren returnere en ny "acces" og "refresh" token i data: {} variablen.
- Hvis "refresh" token er udløbet, vil serveren returnere en statuskode 401, og du skal gå tilbage til login-loopet.
- Hvis serveren returnerer en statuskode 404, er det en ugyldig signatur.
Server Respons Koder
200: Refresh token success.
401: Refresh token udløbet.
404: Refresh token ugyldig.
406: Ugyldig token på baggrund af ugyldig bruger.
WSAPI Dokumentation
Der er to systemer som begge giver mulighed for at læse dokumentation af de kliniske kvalitetsdatabasers webservices: Swagger og Redocs.
Redocs
Hvis du har brug for at undersøge datadefinitioner på webservices, er Redocs det anbefalede system at bruge. Her kan alle versioner af diverse webservices undersøges. Ønsker du at undersøge en datadefinition i Redocs kan det gøres således:
-
Åben WSAPI
-
Åben Redocs ved at vælge "Redocs" i toppen af siden / i menuen.
-
I venstre side kan de nuværende webservices ses i en liste.
-
Tryk på den ønskede webservice, for at folde menuen ud med muligheder.
-
Vælg "Post ____ entry" (f.eks."Post Dhreg entry".)
-
På hovedområdet i skærmen kan datadefinitionen ses i "Report" og "Metadata".
-
Det mest relevante information, kan findes under "Report". Tryk derfor på "Report" for at folde datadefinitionen ud.
-
Her kan den komplette datadefinition undersøges ved at blive ved med at folde ud i "træet".
Swagger / SwaggerUI
Har du brug for at teste transaktioner er Swagger det anbefalede system at gå igennem. Det er også muligt at se datadefinitioner i Swagger, men der er et bedre overblik i Redocs.
SDN:
WSAPI produktions server vil være på sundhedsdatanettet. Det betyder at der skal oprettes en service aftale.
Test-serveren kræver dog ingen service aftale.
Test-miljø:
Prod-miljø: (Udestående)