Nærværende dokument indgår i den samlede dokumentationspakke for stamdataregistret på NSP. Dokumentationspakken giver tilsammen det fulde overblik over dokumentationen.
"Guide til anvendere - Rolleinformation" er målrettet udviklere og arkitekter hos leverandører, som ønsker at anvende funktionaliteten udstillet af servicen "Rolleinformation" i stamdataservicen
Stamdataservicen udstiller en REST-service der kan anvendes til at hente de nationale roller (externalName) der er tilknyttet et SSN.
Servicen udstiller følgende snitflade:
Herunder gengives den aktuelle snitflade som den ser ud. Den mest aktuelle specifikation kan findes i sourcekoden (som pt. hostes her https://git.nspop.dk/projects/COM/repos/stamdatamodul/browse).
openapi: 3.0.0
info:
title: Rolle Information REST Service
description: Intern NSP service, der kan anvendes til at slå informationer om roller op.
version: "1.0.0"
servers:
- url: '%endpoint%'
paths:
/stamdata-rolleinformation/roller/{ssn}:
get:
summary: Hent gyldige nationale roller for et SSN.
description: >
Returnerer en liste af nationale roller, der er gyldige dags dato (ValidFrom <= NOW()
AND (ValidTo > NOW() OR ValidTo IS NULL)) for det angivne SSN.
Findes der ingen gyldige roller returneres 404 med en tom JSON body.
parameters:
- in: path
name: ssn
schema:
type: string
maxLength: 64
required: true
description: Subject Serial Number (SSN)
example: "CVR:25450442-RID:22019616"
responses:
200:
description: OK - en eller flere gyldige roller fundet.
content:
application/json:
schema:
$ref: '#/components/schemas/roller'
400:
description: Ugyldig forespørgsel (fx tomt SSN eller SSN der overstiger 64 tegn).
404:
description: Der findes ingen gyldige roller for det angivne SSN.
500:
description: Intern serverfejl.
components:
schemas:
roller:
type: array
items:
$ref: '#/components/schemas/rolle'
rolle:
type: object
required:
- externalName
properties:
externalName:
type: string
description: Det eksterne navn for rollen som registreret i nationalRoles. |
Servicen kan tilgås på nedenstående endpoint, hvor stamdatahost skal tilrettes til den aktuelle host.
| Endpoint | Url |
|---|---|
| Hent roller for et SSN | http://stamdatahost/stamdata-rolleinformation/roller/{ssn} |
I dette eksempel kaldes servicen med et SSN fra et POCES-certifikat. Se i øvrigt API-specifikationen længere oppe.
Request
Request i form af et curl-udtryk. Bemærk at : i SSN-værdien skal URL-encodes til %3A.
curl --location 'http://stamdatahost/stamdata-rolleinformation/roller/UI%3ADK-E%3AG%3A594f7fc0-30cf-4b83-8521-4d3f810b3107' |
Response
Der svares med HTTP statuskode 200 og følgende JSON.
[
{ "externalName": "nspPlejeAssR3" }
]
|
I dette eksempel slås der op på et SSN med tre gyldige roller. Servicen returnerer dem alle
Request
Request i form af et curl-udtryk. Bemærk at : i SSN-værdien skal URL-encodes til %3A.
curl --location 'http://stamdatahost/stamdata-rolleinformation/roller/UI%3ADK-E%3AG%3Ab57fa5ad-493e-448b-8759-cfcb844b1f1f' |
Response
Der svares med HTTP statuskode 200 og følgende JSON.
[
{ "externalName": "nspPlejeAssR3" },
{ "externalName": "nspSundAssistR1" },
{ "externalName": "nspSundAssistR2" }
]
|
Hvis SSN'et ikke findes i nationalRoles, eller alle rækker har ValidFrom/ValidTo uden for nuværende tidspunkt, svares der med HTTP statuskode 404 og en tom JSON-body.
Request
Request i form af et curl-udtryk. Bemærk at : i SSN-værdien skal URL-encodes til %3A.
curl --location 'http://stamdatahost/stamdata-rolleinformation/roller/UI%3ADK-E%3AG%3Afed28411-15b4-47a3-81f4-4e284b7c581c' |
Response
HTTP statuskode 404.
[] |
Tomt SSN eller SSN længere end 64 tegn afvises med HTTP statuskode 400 og en plain-text fejlbesked.
Request
Request i form af et curl-udtryk. Bemærk at : i SSN-værdien skal URL-encodes til %3A.
ccurl --location 'http://stamdatahost/stamdata-rolleinformation/roller/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' |
Response
HTTP statuskode 404.
SSN må højst være 64 tegn. |