Ga naar hoofdinhoud
Versie: 0.0.1

Specificatie

De OKAP specificatie (momenteel geïmplementeerd / gespecificeerd in gRPC) bestaat uit 2 onderdelen, de onboarding en configuratie. De onboarding methodes wordt gebruikt om een veilig verbinding op te zetten tussen het XIS en dienstverlener en de configuratie methodes worden vervolgens gebruikt door het XIS om de door de dienstverlener aangeboden diensten te configureren en patiënten aan en af te melden.

Onboarding methodes​

GetMetadata​

De GetMetadata methode wordt gebruikt om metadata van de dienstverlener op te halen.

Request​

Het GetMetadataRequest object heeft geen velden, als de koppeling niet is gelukt wordt dat gecommuniceerd door een foutmelding terug gegeven. Zie foutmeldingen voor meer details..

message GetMetadataRequest {}

Response​

message GetMetadataResponse {
  // Formele naam van de leverancier van de dienstverlener zoals ingeschreven bij de KvK.
  string supplierFormalName = 1;
  // Naam om te tonen in het XIS voor identificatie doeleinden voor de zorgverlener.
  string supplierDisplayName = 2;
  // Naam van het product (overkoepelend systeem).
  string productName = 3;
  // Huidig versie van dit product.
  string version = 4;
}

Register​

De Register methode wordt gebruikt om een koppelverzoek in te schieten bij de dienstverlener.

Request​

message RegisterRequest {
  // Formele naam van de te koppelen organisatie (verantwoordelijk voor het XIS)
  // zoals ingeschreven bij de KvK.
  string organisationFormalName = 1;
  // Naam om te tonen in het product van de dienstverlener ter identificatie
  // van de te koppelen organisatie.
  string organisationDisplayName = 2;
  // Identifier voor deze organisatie.
  string organisationIdentifier = 3;
  // Type van identifier gebruikt bij *organisationIdentifier*, bijvoorbeeld:
  // AGB-code, BIG registratie of KvK-nummer.
  string organisationIdentifierType = 4;
  // Datatype voor het configureren van het authenticatie middel dat het XIS gaat
  // gebruiken richting de dienstverlener.
  XISAuthConfiguration auth = 5;
}

Response​

message RegisterResponse {
  // Reeks tekens die deze registratie identificeert. Deze moet later bij het
  // completeren van de koppelingen meegegeven worden.
  string reference = 1;
}

Gebruikte datatypen​

message XISAuthConfiguration {
  // Geeft aan welke methode wordt gebruikt, mTLS of BearerToken
  XISAuthMethod method = 1;
  // Methode afhankelijke configuratie
  oneof config {
    MTLSConfigurationParams mtlsConfig = 2;
    BearerTokenConfigurationParams apiTokenConfig = 3;
  }
}

enum XISAuthMethod {
  mTLS = 0;
  BearerToken = 1;
}

message MTLSConfigurationParams {
  // Fingerprint van de publieke sleutel van het client certificaat dat gebruikt gaat worden om een
  // mTLS verbinding op te zetten.
  // 'sha265:' + hex(sha256(RawSubjectPublicKeyInfo)))
  string publicKey = 1;
}

message BearerTokenConfigurationParams {
  // Reeks karakters dat meegegeven gaat worden als bearer token
  string token = 1;
}

Errors​

// Invalide configuratie voor de gekozen methode
InvalidXISAuthConfiguration;

Zie foutmeldingen voor meer informatie.

CompleteRegistration​

De methode wordt gebruikt om, indien het koppelverzoek is gevalideerd en de registratie token is ontvangen, de koppeling te completeren.

Request​

message CompleteRegistrationRequest {
  // Reeks karakters dat is verkregen met de Register methode.
  string reference = 1;
  // Reeks karakters dat via een side-channel is verkregen van
  // de dienstverlener.
  string registrationToken = 2;
}

Response​

Het response object heeft geen velden, als de koppeling niet is gelukt wordt dat gecommuniceerd door een foutmelding terug gegeven, een succesvol ontvangen response betekent dus een werkende koppeling. Zie foutmeldingen voor meer details.

message CompleteRegistrationResponse {
}

Errors​

// Onbekende reference meegegeven
UnkownReference;
// Invalide registratietoken voor deze reference
InvalidRegistrationToken;

Zie foutmeldingen voor meer informatie.

Configuratie methodes​

ConfigureCallback​

Deze methode wordt gebruikt om een service met bijbehorende callbacks (de manier waarop de dienstverlener patientgegevens kan opvragen of opsturen bij / naar het XIS) te configureren.

Request​

message ConfigureCallbackRequest {
  // De identifier van van de service waarvan de callback wordt geconfigureerd
  string serviceId 1;
  // Enabled geeft aan of deze service aan of uit staat
  bool enabled = 2;
  // Datatype voor het configureren van het opsturen van gegevens naar het XIS
  CallbackConfig fetch = 3;
  // Datatype voor het configureren van het ophalen van gegevens bij het XIS
  CallbackConfig push = 4;
}

Response​

De ConfigureCallbackResponse is een weerspiegeling van de ConfigureCallbackRequest waarin staat wat de instellingen zijn voor deze service na het afhandelen van dit request.

message ConfigureCallbackResponse {
  // De identifier van van de service waarvan de callback wordt geconfigureerd
  string serviceId 1;
  // Enabled geeft aan of deze service aan of uit staat
  bool enabled = 2;
  // Datatype voor het configureren van het opsturen van gegevens naar het XIS
  CallbackConfig fetch = 3;
  // Datatype voor het configureren van het ophalen van gegevens bij het XIS
  CallbackConfig push = 4;
}

In sommige gevallen is de response aangevuld met extra informatie die het XIS niet zelf kan of wil aangeven. Een voorbeeld hiervan is het inregelen van een mTLS verbinding voor een fetch of push protocol. De dienstverlener is in dit geval degene die aangeeft met welk certificaat deze zal gaan verbinden met het XIS.

Hier een voolbeed hiervan in pseudocode

// Request
ConfigureCallbackRequest {
  service: "service-1",
  enabled: true,
  fetch: CallbackConfig{
    protocol: "example-proto",
    config: map<string,string>{
      "endpoint": "https://api.xis.nl"
    },
    auth: ProtocolAuthConfiguration{
      method: "mTLS"
    }
  },
  ...
}

// Response
ConfigureCallbackRequest {
  service: "service-1",
  enabled: true,
  fetch: CallbackConfig{
    protocol: "example-proto",
    config: map<string,string>{
      "endpoint": "https://api.xis.nl"
    },
    auth: ProtocolAuthConfiguration{
      method: "mTLS"
      configuration: map<string,string>{
        "publicKey": "sha256:fba9a3bc0fdc8095a15c910862c5cead5b20399ce78eea3a89da087059369c61",
        "CN": "dienstverlener-voorbeeld"
      }
    }
  },
  ...
}

Gebruikte datatypen​

message CallbackConfig {
  // String die het gebruikte protocol identificeerd.
  string protocol = 1;
  // Protocol afhankelijke configuratie.
  map<string,string> config = 2;
  // Datatype voor het configureren van het authenticatie middel dat de dienstverlener
  // gaat gebruiken richting het XIS.
  ProtocolAuthConfiguration auth = 3;
}

message ProtocolAuthConfiguration {
  // String die het gebruikte authenticatie protocol / methode identificeerd.
  string method = 1;
  // Map<string,string> voor het configureren van het authenticatie middel dat de dienstverlener
  // gaat gebruiken richting het XIS voor deze callback.
  map<string, string> configuration = 2;
}

Errors

// Onbekende service
UnknownService
// Onbekende protocol
UnknownProtocol
// Invalide procotol configuratie voor het aangegeven protocol
InvalidProcotolConfig
// Authenticatie methode onbekend
UnknownAuthMethod
// Invalide authorizatie configuratie voor het aangegeven protocol
InvalidProcotolAuthConfig

Zie foutmeldingen voor meer informatie.

ListServices​

Deze methode wordt door het XIS gebruikt om een lijst op de te vragen van beschikbare diensten die de dienstverlener aanbiedt aan dit XIS en de huidige configuratie voor deze diensten.

Request​

message ListServicesRequest {
}

Response​

message ListServicesResponse {
  // ServiceDefinition is een lijst van beschikbare diensten
  repeated ServiceDefinition availableServices = 1;
  // ServiceConfiguration is een lijst van configuraties die per beschikbare dienst
  // de actuale configuratie van die dienst aangeeft
  repeated ServiceConfiguration configurations = 2;
}

Gebruikte datatypen​

message ServiceDefinition {
  // Identifier voor deze dienst
  string id = 1;
  // Naam van deze dienst bedoelt voor weergave aan menselijke gebruikers
  string name = 2;
  // Omschrijving van deze dienst bedoelt voor weergave aan menselijke gebruikers
  string description = 3;
  // De aanmeld policy voor deze dienst
  SubscriptionPolicy subscriptionPolicy = 4;
  // De toestemmings policy voor deze dienst, alleen
  // te gebruiken indien de SubscriptionPolicy de
  // waarde 'optin' (1) bevat.
  ConsentPolicy consentPolicy = 5;
  // Lijst van beschikbare ophaal protocollen waar
  // deze service mee bekend is
  repeated ProtocolDefinition fetchProtocols = 6;
  // Lijst van beschikbare terugstuur protocollen waar
  // deze service mee bekend is
  repeated ProtocolDefinition pushProtocols = 7;
}

enum SubscriptionPolicy {
  // Default waarde, niet gebruiken. Sommige programeertalen
  // geven een default waarde van 0 op het moment dat deze
  // niet expliciet gezet wordt.
  subnone = 0;
  // Geeft een optin policy aan, d.w.z. de dienstverlener
  // gaat ervan uit dat het XIS een patient actief
  // aanmeldt.
  optin = 1;
  // Geeft een optout policy aan, d.w.z. de dienstverlener
  // gaat ervan uit dat het XIS alle patienten aanmeldt
  // tenzij een patient expliciet heeft aangegeven dat deze
  // dat niet wil.
  optout = 2;
}

// Consentpolicy is alleen van toepassing op het moment dat
// de SubscriptionPolicy de waarde optin (1) bevat.
enum ConsentPolicy {
  consentnone = 0;
  // Geeft aan dat een patient expliciet toestemming moet
  // geven voordat deze voor deze dienst aangemeld kan worden.
  explicit = 1;
  // Geeft aan dat de aanmelding kan plaatsvinden onder
  // veronderstelde toestemming. M.a.w. een patiënt hoeft niet
  // expliciet toestemming te geven.
  presumed = 2;
}

message ProtocolDefinition {
  // Identifier voor een ophaal / terugstuur protocol
  // dat ondersteund wordt door de bovenliggende service
  string protocol = 1;
  // Lijst van beschikbare authenticatie protocollen
  // dit ophaal / terugstuur protocol
  repeated string authMethods = 2;
}

message ServiceConfiguration {
  // Het service veld bevat de identifier van de dienst
  // waarom deze configuratie op van toepassing is
  string serviceId 1;
  // Geeft aan of deze dienst momenteel in ingeschakeld
  bool enabled = 2;
  // Configuratie voor het ophalen van patiëntgegevens door deze
  // dienst bij het XIS
  CallbackConfig fetch = 3;
  // Configuratie voor het terugsturen van patiëntgegevens door deze
  // dienst bij het XIS
  CallbackConfig push = 4;
}

message CallbackConfig {
  // Identifier van het protocol dat gebruikt moet / gaat
  // worden door de dienstverlener voor het
  // ophalen / terugsturen van patiëntgegevens
  string protocol = 1;
  // Map<string,string> waarin protocol afhankelijke instellingen
  // worden vastgelegd
  map<string,string> config = 2;
  // Datatype waarin staat hoe de authenticatie voor dit
  // ophaal / terugstuur protocol is ingeregeld
  ProtocolAuthConfiguration auth = 3;
}

message ProtocolAuthConfiguration {
  // Identifier voor de authentie protocol
  string method = 1;
  // Map<string,string> waarin authenticatie protocol
  // afhankelijke instellingen worden vastgelegd
  map<string, string> configuration = 2;
}

UpdatePatientRegistration​

Deze methode wordt gebruikt om patienten aan en af te melden voor een specifieke dienst.

Request​

message UpdatePatientRegistrationRequest {
  // De identifier van de dienst waarvoor wordt aan- of afgemeld.
  string serviceId = 1;
  // Lijst van patiëntregistraties die de dienstverlener moet
  // instellen / verwerken.
  repeated PatientRegistrationData PatientRegistrationData = 2;
}

Response​

message UpdatePatientRegistrationResponse {
  // Lijst met alle errors die zijn opgetreden bij het
  // verwerken van de opgestuurde registratielijst
  repeated PatientRegistrationError errors = 2;
}

Gebruikte datatypen​

message PatientRegistrationData {
  // Patientmetadata van de patient die wordt
  // aangemeld / afgemeld
  PatientMeta subject = 1;
  // Geeft aan of deze patiënt aangemeld of afgemeld moet
  // zijn na het aanroepen van deze methode
  bool registered = 2;
  // Protocol metadata die nodig is voor het
  // ophalen / terugsturen van gegevens voor specifiek deze patient.
  map<string, string> callbackProtocolMeta = 3;
}

message PatientMeta {
  // Identifier voor deze patient, gebruikt om deze patient
  // (in ieder geval binnen deze dienst maar bij voorkeur
  // ook buiten deze dienst) uniek te identificeren.
  string identifier = 1;
  // Type van identifier die meegestuurd wordt, bijv. BSN
  string identifierType = 2;
  // Voornaam van patiënt
  string firstname = 3;
  // Achternaam van patiënt
  string surname = 4;
  // Voorvoegsel van patiënt
  string surnamePrefix = 5;
  // Geboortedatum van patiënt
  string birthdate = 6;
  // Straatnaam van patiënt
  string street = 7;
  // Huisnummer van patiënt
  string streetNumber = 8;
  // Huisnummerextentie van patiënt
  string streetNumberExtension = 9;
  // Postcode van patiënt
  string postalCode = 10;
  // Woonplaats van patiënt
  string city = 11;
  // Landcode van patiënt (ISO 3166-1 alpha-2)
  string country = 12;
  // Map<string,string> voor extra, niet door OKAP
  // gespecificeerde, metadata van de patiënt.
  map<string, string> extra = 13;
}

message PatientRegistrationError {
  // Komt overeen met de index van de desbetreffende patient
  // in UpdatePatientRegistrationRequest.PatientRegistrationData.
  int32 index = 1;
  // De daadwerkelijke foutbeschijving.
  OKAPError error = 2;
}

message OKAPError {
  // Code uit de OKAP error codes die aangeeft wat de fout inhoudt
  // bedoeld voor afhandeling door machines.
  OKAPErrorCode code = 2;
  // Omschrijving van de fout bedoeld voor afhandeling door mensen.
  string message = 3;
}

Errors​

// Onbekende service
UnknownService

Zie foutmeldingen voor meer informatie.

ListPatientRegistration​

Request​

message ListPatientRegistrationRequest {
  // De identifier van de dienst waarvan de huidige registraties
  // worden opgevraagd.
  string serviceId = 1;
}

Response​

message ListPatientRegistrationResponse {
  // Lijst met huidige registraties voor deze dienst.
  repeated PatientRegistrationData PatientRegistrationData = 2;
}

Gebruikte datatypen​

message PatientRegistrationData {
  // Patientmetadata van de patient die wordt
  // aangemeld / afgemeld
  PatientMeta subject = 1;
  // Geeft aan of deze patiënt aangemeld of afgemeld moet
  // zijn na het aanroepen van deze methode
  bool registered = 2;
  // Protocol metadata die nodig is voor het
  // ophalen / terugsturen van gegevens voor specifiek deze patient.
  map<string, string> callbackProtocolMeta = 3;
}

message PatientMeta {
  // Identifier voor deze patient, gebruikt om deze patient
  // (in ieder geval binnen deze dienst maar bij voorkeur
  // ook buiten deze dienst) uniek te identificeren.
  string identifier = 1;
  // Type van identifier die meegestuurd wordt, bijv. BSN
  string identifierType = 2;
  // Voornaam van patiënt
  string firstname = 3;
  // Achternaam van patiënt
  string surname = 4;
  // Voorvoegsel van patiënt
  string surnamePrefix = 5;
  // Geboortedatum van patiënt
  string birthdate = 6;
  // Straatnaam van patiënt
  string street = 7;
  // Huisnummer van patiënt
  string streetNumber = 8;
  // Huisnummerextentie van patiënt
  string streetNumberExtension = 9;
  // Postcode van patiënt
  string postalCode = 10;
  // Woonplaats van patiënt
  string city = 11;
  // Landcode van patiënt (ISO 3166-1 alpha-2)
  string country = 12;
  // Map<string,string> voor extra, niet door OKAP
  // gespecificeerde, metadata van de patiënt.
  map<string, string> extra = 13;
}

Errors​

// Onbekende service
UnknownService

Zie foutmeldingen voor meer informatie.

Foutmeldingen​

OKAP maakt gebruik van door OKAP gedefinieerde foutcodes en zal deze in in het google.rpc.Status 'details' veld plaatsen. De gRPC errors zullen de gRPC foutcode INVALID_ARGUMENT bevatten.

enum OKAPErrorCode {
    None = 0;
    // Invalide configuratie voor de gekozen methode
    InvalidXISAuthConfiguration = 1;
    // Onbekende reference meegegeven
    UnkownReference = 2;
    // Invalide registratietoken voor deze reference
    InvalidRegistrationToken = 3;
    // Onbekende service
    UnknownService = 4;
    // Onbekend protocol
    UnknownProtocol = 5;
    // Invalide procotol configuratie voor het aangegeven protocol
    InvalidProcotolConfig = 6;
    // Authenticatie methode onbekend
    UnknownAuthMethod = 7;
    // Invalide authorizatie configuratie voor het aangegeven protocol
    InvalidProcotolAuthConfig = 8;
}

message OKAPError {
    // Code bedoeld voor afhandeling door machines
    OKAPErrorCode code = 1;
    // Bericht bedoeld voor afhandeling door mensen
    string message = 2;
}
Laatst bijgewerkt op