OpenAPI-specificatie (Swagger-specificatie) van het logcomponent om modellen en client te genereren.
Merk op dat productiesystemen deze specificatie exact volgen. Tijdens valideren bij MedMij (acceptatietests) kan onze testtooling voor nu ook een lege respons teruggeven op ingestuurde loggebeurtenissen. Deze zijn niet beschreven in het OpenAPI-document bij Release 2. Logclients met een gegenereerd model breken daarop mogelijk af met een exceptie na een lege respons bij 200 OK of 404 NOT FOUND waar zij een JSON-document verwachten. Tijdens de tests leidt dit voor weinig deelnemers tot moeilijkheden, maar het is goed daar bewust van te zijn tijdens het MedMij-validatietraject en als nodig de excepties op logging op te vangen wanneer het parsen van een JSON-body in logresultaat mislukt.
JSON
{
"swagger": "2.0",
"info": {
"title": "MedMij Logging API",
"version": "1.0"
},
"host": "acc-api.medmij.nl",
"basePath": "/eagleeye/v1",
"tags": [
{
"name": "Logregels",
"description": "Verzamelingen van logregels"
},
{
"name": "Aanleveringen",
"description": "Opvragen van aanleveringen"
}
],
"paths": {
"/swagger": {
"get": {
"tags": [],
"x-ISC_CORS": true,
"summary": "Get Swagger spec of this API",
"operationId": "OpenAPI",
"produces": [
"application/json"
],
"security": [
{
"basicAuth": []
}
],
"parameters": [],
"responses": {
"200": {
"description": "Succes"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error"
}
}
}
},
"/logs": {
"get": {
"tags": [
"Logregels"
],
"summary": "Incrementeel opvragen van gevalideerde logregels",
"description": "Incrementeel opvragen van gevalideerde logregels",
"operationId": "GetLogregels",
"produces": [
"application/json"
],
"parameters": [
{
"in": "query",
"name": "from",
"description": "UTC-timestamp van eerste op te vragen logregel. Bij leeg wordt vanaf het begin gestart",
"type": "string",
"format": "date-time"
},
{
"in": "query",
"name": "to",
"description": "UTC-timestamp van laatste op te vragen logregel. Bij leeg wordt tot aan het einde bevraagd",
"type": "string",
"format": "date-time"
},
{
"in": "query",
"name": "count",
"description": "Maximaal aantal logregels in het antwoordbericht",
"type": "integer",
"format": "int32"
},
{
"in": "query",
"name": "valid",
"description": "Filter op logregels zonder (valid=true) of met (valid=false) functionele fouten",
"type": "boolean"
},
{
"in": "query",
"name": "aanlevering",
"description": "Opvragen van logrecords voor de Aanlevering met het opgegeven id",
"type": "string"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/GetLogregelsResponse"
}
},
"403": {
"description": "U hebt niet de juiste autorisatie",
"schema": {
"$ref": "#/definitions/ApiResponse"
}
},
"404": {
"description": "Aanlevering is niet gevonden",
"schema": {
"$ref": "#/definitions/ApiResponse"
}
},
"500": {
"description": "Probleem in de MedMij Logging API, probeer het later opnieuw",
"schema": {
"$ref": "#/definitions/ApiResponse"
}
}
}
},
"post": {
"tags": [
"Logregels"
],
"summary": "Ontvang en verwerk een verzameling van logregels",
"operationId": "ProcessLogregels",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "logregels",
"in": "body",
"description": "Verzameling van logregels",
"schema": {
"$ref": "#/definitions/Logregels"
},
"required": true
}
],
"description": "Ontvang en verwerk een verzameling van logregels",
"responses": {
"200": {
"description": "De verzameling van logregels is geaccepteerd na technische validatie",
"schema": {
"$ref": "#/definitions/PostResponse"
}
},
"400": {
"description": "Er zijn technische fouten in de verzameling van logregels",
"schema": {
"$ref": "#/definitions/ApiResponse"
}
},
"403": {
"description": "U hebt niet de juiste autorisatie",
"schema": {
"$ref": "#/definitions/ApiResponse"
}
},
"500": {
"description": "Probleem in de MedMij Logging API, probeer het later opnieuw",
"schema": {
"$ref": "#/definitions/ApiResponse"
}
}
}
}
},
"/aanleveringen": {
"get": {
"tags": [
"Aanleveringen"
],
"summary": "Opvragen van aanleveringen met hun status",
"operationId": "GetAanleveringen",
"produces": [
"application/json"
],
"parameters": [
{
"in": "query",
"name": "id",
"description": "Opvragen van aanlevering met het opgegeven id",
"type": "string"
},
{
"in": "query",
"name": "from",
"description": "UTC-timestamp van eerste op te vragen aanlevering. Bij leeg wordt vanaf het begin gestart",
"type": "string",
"format": "date-time"
},
{
"in": "query",
"name": "to",
"description": "UTC-timestamp van laatste op te vragen aanlevering. Bij leeg wordt tot aan het einde bevraagd",
"type": "string",
"format": "date-time"
},
{
"in": "query",
"name": "count",
"description": "requested page-size",
"type": "integer",
"format": "int32"
},
{
"in": "query",
"name": "status",
"description": "Filter on Status=Accepted|Rejected|InternalError",
"type": "string"
},
{
"in": "query",
"name": "validated",
"description": "Filter on Aanleveringen dat have been functionaly validated",
"type": "boolean"
},
{
"in": "query",
"name": "valid",
"description": "Filter on Aanleveringen dat have functional errors (valid=false) versus errors (valid=true); implies validated=true",
"type": "boolean"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"$ref": "#/definitions/GetAanleveringenResponse"
}
},
"403": {
"description": "U hebt niet de juiste autorisatie",
"schema": {
"$ref": "#/definitions/ApiResponse"
}
},
"500": {
"description": "Probleem in de MedMij Logging API, probeer het later opnieuw",
"schema": {
"$ref": "#/definitions/ApiResponse"
}
}
}
}
}
},
"definitions": {
"Logregels": {
"type": "array",
"items": {
"$ref": "#/definitions/Logregel"
}
},
"Logregel": {
"type": "object",
"properties": {
"event": {
"description": "Alle aan te leveren logregels bevatten een event-object",
"$ref": "#/definitions/Event"
},
"request": {
"description": "De logregels van alle verzonden en ontvangen verzoeken bevatten een request-object",
"$ref": "#/definitions/Request"
},
"response": {
"description": "De logregels van alle verzonden en ontvangen antwoorden bevatten een response object",
"$ref": "#/definitions/Response"
},
"error": {
"description": "De logregels van alle fouten in het proces bevatten een error-object",
"$ref": "#/definitions/Error"
},
"information": {
"description": "De logregels van het type result_gathering_information bevatten een information-object met daarin een lijst met de namen van succesvol opgehaalde data-objecten, een lijst van opgehaalde data-objecten waarvan de waarde leeg is en een lijst van onsuccesvol opgehaalde data-objecten",
"$ref": "#/definitions/Information"
}
},
"additionalProperties": false
},
"Event": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Event Type",
"enum": [
"send_authorization_request",
"receive_authorization_request",
"show_landing_page",
"authorization_request_error",
"show_authorization_request_error_page",
"send_authorization_request_error",
"send_authentication_request",
"send_authorization_cancellation",
"receive_authentication_response",
"receive_authorization_cancellation",
"receive_authentication_error",
"send_artifact_resolution_request",
"receive_artifact_response",
"receive_artifact_request_error",
"show_authentication_error_page",
"result_availability_check",
"availability_check_error",
"show_availability_check_error_page",
"show_consent_page",
"receive_consent",
"send_authorization_response",
"send_authorization_cancellation",
"receive_authorization_response",
"send_token_request",
"receive_token_request",
"send_availability_check_error",
"send_token_response",
"send_token_request_error",
"receive_token_response",
"receive_token_request_error",
"send_resource_request",
"receive_resource_request",
"result_gathering_information",
"send_resource_response",
"send_resource_request_error",
"send_resource_error_response",
"receive_resource_response",
"receive_availability_check_error",
"receive_resource_request_error",
"receive_resource_error_response"
],
"example": "send_authorization_request"
},
"location": {
"type": "string",
"description": "De hostname van deelnemer die de logregel vastlegd",
"example": "mijn.pgo.nl"
},
"datetime": {
"type": "string",
"format": "date-time",
"description": "De datum, het tijdstip en de tijdzone van de gebeurtenis",
"example": "2023-03-28T22:14:23.618+01:00"
},
"session_id": {
"type": "string",
"description": "Het identificerende kenmerk van de sessie bij de deelnemer, bij voorkeur een UUID",
"example": "c6a27d45-4316-464e-81e0-48d5dbccacbb"
},
"trace_id": {
"type": "string",
"description": "Het identificerende kenmerk van het proces waarbinnen de stap wordt uitgevoerd, vastgelegd als UUID",
"example": "79dc6181-6239-4fdd-ad98-594312aeac71"
}
},
"additionalProperties": false
},
"Request": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Het unieke identificerende kenmerk (UUID) van het verzoek dat door versturende en ontvangende partij gebruikt wordt",
"example": "8b5d6cb2-a2c0-4893-bd97-240621c3e488"
},
"method": {
"type": "string",
"description": "De gebruikte http method",
"enum": [
"get",
"post",
"put"
],
"example": "get"
},
"client_id": {
"type": "string",
"description": "De hostname van de verzender van het verzoek",
"example": "mijn.pgo.nl"
},
"server_id": {
"type": "string",
"description": "De hostname van de ontvanger van het verzoek",
"example": "as.dva.nl"
},
"uri": {
"type": "string",
"description": "De URI waar het verzoek naartoe wordt gestuurd",
"example": "https://api.as.dva.nl/2.0.0/authorize"
},
"provider_id": {
"type": "string",
"description": "Voor authorization en resource request: Het identificerende kenmerk (MedMij Aanbiedersnaam) van de betrokken aanbieder",
"example": "een.huisarts@medmij"
},
"response_type": {
"type": "string",
"description": "Voor authorization request: Deze heeft, zolang binnen het MedMij netwerk alleen gebruikgemaakt wordt van de OAuth2 Authorization Code Grant, altijd de waarde 'code'",
"enum": [
"code"
],
"example": "code"
},
"redirect_uri": {
"type": "string",
"description": "Voor authorization request: De URI waar het resultaat naartoe gestuurd moet worden. Deze wordt gebruikt voor de redirect terug naar de DVP",
"example": "https://mijn.pgo.nl/medmij"
},
"state": {
"type": "string",
"description": "Voor authorization request: De OAuth2 state parameter",
"example": "ipcxyhlbjtvduydtneoaflwiismwxfmj"
},
"request_type": {
"type": "string",
"description": "Voor Artifact resolution request: Altijd de waarde 'SAML_assertion'",
"enum": [
"SAML_assertion"
],
"example": "SAML_assertion"
},
"grant_type": {
"type": "string",
"description": "Voor token request: De waarde moet 'authorization_code' of 'refresh_token' zijn, waarbij de laatste alleen gebruikt mag worden bij het uitvoeren van een langdurige toestemming",
"enum": [
"authorization_code",
"refresh_token"
],
"example": "authorization_code"
},
"initiated_by": {
"type": "string",
"description": "Voor token request: De waarde moet 'person' of 'machine' zijn, waarbij de laatste alleen gebruikt mag worden bij automatisch verzamelen",
"enum": [
"person",
"machine"
],
"example": "person"
},
"service_id": {
"type": "integer",
"format": "int32",
"description": "Voor resource request: Het identificerende kenmerk (nummer) van de opgevraagde gegevensdienst",
"example": 49
}
},
"additionalProperties": false
},
"Response": {
"type": "object",
"properties": {
"request_id": {
"type": "string",
"description": "De id van het request waar het antwoord bij hoort",
"example": "8b5d6cb2-a2c0-4893-bd97-240621c3e488"
},
"status": {
"type": "integer",
"format": "int32",
"description": "De HTTP status code",
"example": 403
}
},
"additionalProperties": false
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "De waarde van het OAuth2.0 attribuut 'error' wordt overgenomen",
"example": "access_denied"
},
"description": {
"type": "string",
"description": "Omschrijving van de geregistreerde fout. Bij de problemen in de beschikbaarheids- of ontvankelijkheidstoets moeten de waarden no_information_available (bij geen behandelrelatie), invalid_age of blocked worden gebruikt",
"example": "no_information_available"
},
"request_id": {
"type": "string",
"description": "De id van het request waar het antwoord bij hoort",
"example": "8b5d6cb2-a2c0-4893-bd97-240621c3e488"
},
"status": {
"type": "integer",
"format": "int32",
"description": "De HTTP status code",
"example": 403
}
},
"additionalProperties": false
},
"Information": {
"type": "object",
"properties": {
"successful": {
"type": "array",
"description": "Lijst met de namen van succesvol opgehaalde data-objecten",
"items": {
"type": "string"
}
},
"empty": {
"type": "array",
"description": "Lijst met de namen van data-objecten waarvan de waarde leeg is",
"items": {
"type": "string"
}
},
"unsuccessful": {
"type": "array",
"description": "Lijst met de namen van onsuccesvol opgehaalde data-objecten",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
},
"GetLogregelsResponse": {
"allOf": [
{
"$ref": "#/definitions/ApiResponse"
},
{
"type": "object",
"properties": {
"requested-at": {
"description": "UTC-tijdstip van de bevraging",
"type": "string",
"format": "date-time",
"example": "2023-08-21T09:01:45.7384083Z"
},
"aanlevering": {
"description": "aanlevering parameter van de bevraging",
"type": "string"
},
"from": {
"description": "from parameter van de bevraging",
"type": "string",
"format": "date-time",
"example": "2023-03-20T15:14:45.7384083Z"
},
"to": {
"description": "to parameter van de bevraging",
"type": "string",
"format": "date-time",
"example": "2023-03-20T15:14:45.7384083Z"
},
"valid": {
"description": "valid parameter van de bevraging",
"type": "boolean"
},
"next": {
"description": "UTC-tijdstip van het volgende op te vragen record",
"type": "string",
"format": "date-time",
"example": "2023-03-20T15:14:45.7384083Z"
},
"logregels": {
"type": "array",
"items": {
"$ref": "#/definitions/ValidatedLogregel"
}
}
}
}
]
},
"ValidatedLogregel": {
"type": "object",
"properties": {
"id": {
"description": "technisch ID van de regel in de logging service",
"type": "string"
},
"client-name": {
"description": "ClientName van de aanleverende partij",
"type": "string"
},
"modified-at": {
"description": "UTC-tijdstip dat deze logregel is opgeslagen of gewijzigd",
"type": "string",
"format": "date-time",
"example": "2023-08-21T07:57:54.6086065Z"
},
"receive-count": {
"description": "Numerieke waarde die aangeeft hoe vaak de logregel is ontvangen.",
"type": "integer",
"format": "int32"
},
"is-valid": {
"description": "Is de logregel geldig volgens de functionele toetsing?",
"type": "boolean"
},
"valid-before-update": {
"description": "Deze logregel zonder functionele fouten is later overschreven met een logregel die fouten bevat.",
"type": "boolean"
},
"regel": {
"description": "De logregel zoals ontvangen",
"$ref": "#/definitions/Logregel"
},
"fouten": {
"description": "Foutcondities vastgesteld tijdens de de functionele toetsing indien is-valid false",
"type": "array",
"items": {
"$ref": "#/definitions/ValidatieFout"
}
}
}
},
"ValidatieFout": {
"type": "object",
"properties": {
"error": {
"description": "Foutconditie",
"type": "string"
},
"value": {
"description": "Gevonden waarde",
"type": "string"
},
"path": {
"description": "Locatie in het object waar deze fout is vastgesteld",
"type": "string"
}
}
},
"PostResponse": {
"allOf": [
{
"$ref": "#/definitions/ApiResponse"
},
{
"type": "object",
"properties": {
"id": {
"description": "Technisch ID van de aanlevering in de logging service",
"type": "string"
}
}
}
]
},
"GetAanleveringenResponse": {
"allOf": [
{
"$ref": "#/definitions/ApiResponse"
},
{
"type": "object",
"properties": {
"requested-at": {
"description": "UTC-tijdstip van de bevraging",
"type": "string",
"format": "date-time",
"example": "2023-08-21T09:01:45.7384083Z"
},
"from": {
"description": "from parameter van de bevraging",
"type": "string",
"format": "date-time",
"example": "2023-03-20T15:14:45.7384083Z"
},
"to": {
"description": "to parameter van de bevraging",
"type": "string",
"format": "date-time",
"example": "2023-03-20T15:14:45.7384083Z"
},
"status": {
"description": "status parameter van de bevraging",
"type": "boolean"
},
"validated": {
"description": "validated parameter van de bevraging",
"type": "boolean"
},
"valid": {
"description": "valid parameter van de bevraging",
"type": "boolean"
},
"next": {
"description": "UTC-tijdstip van het volgende op te vragen record",
"type": "string",
"format": "date-time",
"example": "2023-03-20T15:14:45.7384083Z"
},
"aanleveringen": {
"type": "array",
"items": {
"$ref": "#/definitions/Aanlevering"
}
}
}
}
]
},
"Aanlevering": {
"type": "object",
"properties": {
"id": {
"description": "Technisch ID van de aanlevering in de logging service",
"type": "string"
},
"registered-at": {
"description": "UTC-tijdstip dat deze aanlevering is opgeslagen",
"type": "string",
"format": "date-time",
"example": "2023-08-21T07:57:54.6086065Z"
},
"client-name": {
"description": "ClientName van de aanleverende partij",
"type": "string"
},
"aantal-logregels": {
"description": "Aantal logregels binnen de aanlevering",
"type": "integer",
"format": "int32"
},
"status": {
"type": "string",
"description": "Status van de aanlevering",
"enum": [
"Accepted",
"Rejected",
"InternalError"
]
},
"is-validated": {
"description": "Is de aanlevering al functioneel getoetst?",
"type": "boolean"
},
"aantal-foute-logregels": {
"description": "Aantal logregels binnen de aanlevering met functionele fouten (bij is-validated = true)",
"type": "integer",
"format": "int32"
},
"api-response": {
"$ref": "#/definitions/ApiResponse"
}
}
},
"ApiResponse": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}