Ga naar hoofdinhoud
Versie: 0.0.2

Specificatie

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

gevaar

OKAPI vereist dat een applicatie die de OKAPI specificatie implementeert zijn GRPC interface alleen over een TLS verbinding aanbiedt.

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 zorginformatiesysteem 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 zorginformatiesysteem)
  // 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 zorginformatiesysteem 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 configuration {
    MTLSConfigurationParams mtlsConfiguration = 2;
    BearerTokenConfigurationParams apiTokenConfiguration = 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 out-of-band kanaal is verkregen van
  // de dienstverlener.
  string authorisationToken = 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 autorisatiecode voor deze reference
InvalidAuthorisationToken;

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 zorginformatiesysteem) 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 zorginformatiesysteem
  CallbackConfiguration fetch = 3;
  // Datatype voor het configureren van het ophalen van gegevens bij het zorginformatiesysteem
  CallbackConfiguration 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 zorginformatiesysteem
  CallbackConfiguration fetch = 3;
  // Datatype voor het configureren van het ophalen van gegevens bij het zorginformatiesysteem
  CallbackConfiguration push = 4;
}

In sommige gevallen is de response aangevuld met extra informatie die het zorginformatiesysteem 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 zorginformatiesysteem.

Hier een voolbeed hiervan in pseudocode

// Request
ConfigureCallbackRequest {
  service: "service-1",
  enabled: true,
  fetch: CallbackConfiguration{
    protocol: "example-proto",
    config: google.protobuf.Struct{
      "endpoint": "https://api.xis.nl"
    },
    auth: ProtocolAuthConfiguration{
      method: "mTLS"
    }
  },
  ...
}

// Response
ConfigureCallbackRequest {
  service: "service-1",
  enabled: true,
  fetch: CallbackConfiguration{
    protocol: "example-proto",
    config: google.protobuf.Struct{
      "endpoint": "https://api.xis.nl"
    },
    auth: ProtocolAuthConfiguration{
      method: "mTLS"
      configuration: google.protobuf.Struct{
        "publicKey": "sha256:fba9a3bc0fdc8095a15c910862c5cead5b20399ce78eea3a89da087059369c61",
        "CN": "dienstverlener-voorbeeld"
      }
    }
  },
  ...
}

Gebruikte datatypen​

message CallbackConfiguration {
  // String die het gebruikte protocol identificeerd.
  string protocol = 1;
  // Protocol afhankelijke configuratie.
  google.protobuf.Struct configuration = 2;
  // Datatype voor het configureren van het authenticatie middel dat de dienstverlener
  // gaat gebruiken richting het zorginformatiesysteem.
  ProtocolAuthConfiguration auth = 3;
}

message ProtocolAuthConfiguration {
  // String die het gebruikte authenticatie protocol / methode identificeerd.
  string method = 1;
  // Map voor het configureren van het authenticatie middel dat de dienstverlener
  // gaat gebruiken richting het zorginformatiesysteem voor deze callback.
  google.protobuf.Struct 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 zorginformatiesysteem gebruikt om een lijst op de te vragen van beschikbare diensten die de dienstverlener aanbiedt aan dit zorginformatiesysteem 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 zorginformatiesysteem een patient actief
  // aanmeldt.
  optin = 1;
  // Geeft een optout policy aan, d.w.z. de dienstverlener
  // gaat ervan uit dat het zorginformatiesysteem 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 zorginformatiesysteem
  CallbackConfiguration fetch = 3;
  // Configuratie voor het terugsturen van patiëntgegevens door deze
  // dienst bij het zorginformatiesysteem
  CallbackConfiguration push = 4;
}

message CallbackConfiguration {
  // Identifier van het protocol dat gebruikt moet / gaat
  // worden door de dienstverlener voor het
  // ophalen / terugsturen van patiëntgegevens
  string protocol = 1;
  // Map waarin protocol afhankelijke instellingen
  // worden vastgelegd
  google.protobuf.Struct configuration = 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 waarin authenticatie protocol
  // afhankelijke instellingen worden vastgelegd
  google.protobuf.Struct configuration = 2;
}

ListServiceConfigurations​

Deze methode wordt door het zorginformatiesysteem gebruikt om een lijst op de te vragen bij de dienstverlener met de daarin de huidige configuratie van de beschikbare diensten.

Request​

message ListServiceConfigurationsRequest {}

Response​

message ListServiceConfigurationsResponse {
    repeated ServiceConfiguration configurations = 2;
}

Gebruikte datatypen​

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 zorginformatiesysteem
  CallbackConfiguration fetch = 3;
  // Configuratie voor het terugsturen van patiëntgegevens door deze
  // dienst bij het zorginformatiesysteem
  CallbackConfiguration push = 4;
}

message CallbackConfiguration {
  // Identifier van het protocol dat gebruikt moet / gaat
  // worden door de dienstverlener voor het
  // ophalen / terugsturen van patiëntgegevens
  string protocol = 1;
  // Map waarin protocol afhankelijke instellingen
  // worden vastgelegd
  google.protobuf.Struct configuration = 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 waarin authenticatie protocol
  // afhankelijke instellingen worden vastgelegd
  google.protobuf.Struct 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 Identifier {
  string type = 1;
  string value = 2;
}

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;
  // Id voor deze patient, gebruikt om deze patient
  // binnen deze dienst uniek te identificeren.
  string id = 3;
  // Protocol metadata die nodig is voor het
  // ophalen / terugsturen van gegevens voor specifiek deze patient.
  google.protobuf.Struct callbackProtocolData = 4;
}

message PatientMeta {
  // Identifiers voor deze patient, gebruikt om deze patient
  // buiten deze dienst uniek te identificeren.
  repeated Identifier identifier = 1;
  // Voornaam van patiënt
  string firstname = 2;
  // Achternaam van patiënt
  string surname = 3;
  // Voorvoegsel van patiënt
  string surnamePrefix = 4;
  // Geboortedatum van patiënt
  string birthdate = 5;
  // Straatnaam van patiënt
  string street = 6;
  // Huisnummer van patiënt
  string streetNumber = 7;
  // Huisnummerextentie van patiënt
  string streetNumberExtension = 8;
  // Postcode van patiënt
  string postalCode = 9;
  // Woonplaats van patiënt
  string city = 10;
  // Landcode van patiënt (ISO 3166-1 alpha-2)
  string country = 11;
  // Map voor extra, niet door OKAPI
  // gespecificeerde, metadata van de patiënt.
  google.protobuf.Struct extra = 12;
}

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

message OKAPIError {
  // Code uit de OKAPI error codes die aangeeft wat de fout inhoudt
  // bedoeld voor afhandeling door machines.
  OKAPIErrorCode code = 1;
  // Omschrijving van de fout bedoeld voor afhandeling door mensen.
  string message = 2;
}

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 = 1;
}

Gebruikte datatypen​

message Identifier {
  string type = 1;
  string value = 2;
}

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;
  // Id voor deze patient, gebruikt om deze patient
  // binnen deze dienst uniek te identificeren.
  string id = 3;
  // Protocol metadata die nodig is voor het
  // ophalen / terugsturen van gegevens voor specifiek deze patient.
  google.protobuf.Struct callbackProtocolData = 4;
}

message PatientMeta {
  // Identifiers voor deze patient, gebruikt om deze patient
  // buiten deze dienst uniek te identificeren.
  repeated Identifier identifier = 1;
  // Type van identifier die meegestuurd wordt, in de meeste
  // gevallen zal dit van het type BSN zijn
  string externalIdentifierType = 2;
  // Voornaam van patiënt
  string firstname = 4;
  // Achternaam van patiënt
  string surname = 5;
  // Voorvoegsel van patiënt
  string surnamePrefix = 6;
  // Geboortedatum van patiënt
  string birthdate = 7;
  // Straatnaam van patiënt
  string street = 8;
  // Huisnummer van patiënt
  string streetNumber = 9;
  // Huisnummerextentie van patiënt
  string streetNumberExtension = 10;
  // Postcode van patiënt
  string postalCode = 11;
  // Woonplaats van patiënt
  string city = 12;
  // Landcode van patiënt (ISO 3166-1 alpha-2)
  string country = 13;
  // Map voor extra, niet door OKAPI
  // gespecificeerde, metadata van de patiënt.
  google.protobuf.Struct extra = 14;
}

Errors​

// Onbekende service
UnknownService

Zie foutmeldingen voor meer informatie.

Event methodes (logging)​

Er is binnen OKAPI rekening gehouden met het feit dat het zorginformatiesysteem op de hoogte wil blijven van uitgevoerd werk door de dienstverlener. Als een dienst een actie uitvoert kan deze dat vastleggen in een Event en deze opvraagbaar maken zodat het zorginformatiesysteem inzicht krijgt in het uitgevoerde werk. Dit kan ingezet worden voor logging / audit doeleinden, maar wellicht ook om deze informatie te tonen aan een arts in de UI van het zorginformatiesysteem. Er is binnen OKAPI dan ook niet gespecificeerd wat er vastgelegd moet worden, dit is aan de dienstverlener om te bepalen.

GetEvents​

De eerste methode is voor het gepagineerd opvragen van events van een bepaald type, eventueel binnen een bepaalde service en voor een bepaalde patient.

GetEventsRequest​

message GetEventsRequest {
    // De verzochte pagina
    int32 page = 2;
    // Hoeveel events per pagina worden meegegeven
    int32 perPage = 3;
    // De query die bepaald welke events
    // worden teruggegeven
    repeated Query query = 4;
}

GetEventsResponse​

message GetEventsResponse {
    // De verzochte pagina
    int32 page = 2;
    // Hoeveel events per pagina worden meegegeven
    int32 perPage = 3;
    // De events die zijn gevonden
    repeated Event events = 4;
}

Gebruikte datatypes​

message Event {
    // Tijdstip waarop het event heeft plaatsgevonden
    // Unix timestmp in milliseconden
    uint64 timestamp = 1;
    // Type van het event
    string type = 2;
    // Id van de dienst die het event
    // heeft geregistreerd
    string serviceId = 3;
    // Id van de patient waarom dit event
    // betrekking heeft
    string patientId = 4;
    // Event type afhankelijke data
    google.protobuf.Struct payload = 5;
}

message Query {
    // Filtert events die hebben plaatgevonden
    // na of op de waarde in het veld
    // (Event.timestamp >= Query.start), formaat
    // is een Unix timestamp in milliseconden
    uint64 start = 1;
    // Filtert events die hebben plaatgevonden
    // voor de waarde in het veld
    // (Event.timestamp < Query.end), formaat
    // is een Unix timestamp in milliseconden
    uint64 end = 2;
    // Type van het event
    string type = 3;
    // Id van de service (ServiceDefinition.id)
    string serviceId = 4;
    // Id van de patient (PatientRegistrationData.id)
    string patientId = 5;
}

Errors​

// Er zijn niet genoeg events om deze pagina te bereiken.
// Wordt teruggegeven als de pagina niet bestaat
InvalidPage

Zie foutmeldingen voor meer informatie.

GetEventsStream​

De GetEventStream methode heeft dezelfde functie als de GetEvents methode alleen geeft deze methode de gevonden events terug in een stream van Events. Deze methode kan dus gebruikt worden om realtime Events te ontvangen.

GetEventsStreamRequest​

message GetEventsStreamRequest {
    // De query die bepaald welke events
    // worden teruggegeven
    repeated Query query = 2;
}

Response​

message Event {
    // Tijdstip waarop het event heeft plaatsgevonden
    // Unix timestmp in milliseconden
    uint64 timestamp = 1;
    // Type van het event
    string type = 2;
    // Id van de dienst die het event
    // heeft geregistreerd
    string serviceId = 3;
    // Id van de patient waarom dit event
    // betrekking heeft
    string patientId = 4;
    // Event type afhankelijke data
    google.protobuf.Struct payload = 5;
}

Gebruikte datatypes​

message Query {
    // Filtert events die hebben plaatgevonden
    // na of op de waarde in het veld
    // (Event.timestamp >= Query.start), formaat
    // is een Unix timestamp in milliseconden
    uint64 start = 1;
    // Filtert events die hebben plaatgevonden
    // voor de waarde in het veld
    // (Event.timestamp < Query.end), formaat
    // is een Unix timestamp in milliseconden
    uint64 end = 2;
    // Type van het event
    string type = 3;
    // Id van de service (ServiceDefinition.id)
    string serviceId = 4;
    // Id van de patient (PatientRegistrationData.id)
    string patientId = 5;
}

Foutmeldingen​

OKAPI maakt gebruik van door OKAPI 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 OKAPIErrorCode {
    None = 0;
    // Invalide configuratie voor de gekozen methode
    InvalidXISAuthConfiguration = 1;
    // Onbekende reference meegegeven
    UnkownReference = 2;
    // Invalide autorisatiecode voor deze reference
    InvalidAuthorisationToken = 3;
    // Onbekende service
    UnknownService = 4;
    // Onbekend protocol
    UnknownProtocol = 5;
    // Invalide procotol configuratie voor het aangegeven protocol
    InvalidProcotolConfig = 6;
    // Authenticatie methode onbekend
    UnknownAuthMethod = 7;
    // Invalide authorisatie configuratie voor het aangegeven protocol
    InvalidProcotolAuthConfig = 8;
    // Er zijn niet genoeg events om deze pagina te bereiken
    InvalidPage = 9;
}

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