diff --git a/api/ui_api.swagger.yaml b/api/ui_api.swagger.yaml index e3c50dd..4b77aed 100644 --- a/api/ui_api.swagger.yaml +++ b/api/ui_api.swagger.yaml @@ -24,9 +24,12 @@ servers: tags: - name: core description: |- - Functionality that cross-cuts API concerns, such as authentication. + API for cross-cutting API concerns, such as authentication. TBD. - + - name: patient + description: |- + API for retrieving medical dossier data and concerns based on looking up a + specific patient. - name: QoC description: |- API related to Quality of Care features @@ -41,6 +44,138 @@ tags: As well as a 'config' view where they see _all_ care programs that could possibly be relevant for that customer, where the customer can preview the report (essentially, run the report as normal), favourite something they don't get by default, or unfavourite something they get by default. paths: + /patient/base: + get: + tags: + - patient + summary: Get basic personal info not directly related to their medical dossier + responses: + '200': + description: Basic personal information for the patient is returned. + content: + application/json: + schema: + type: object + properties: + bsn: + description: |- + Patient SSN (dutch: _BSN_). Always 9 digits, left-0-padded if necessary. + If unknown or left blank, will be 9 zeroes. + type: string + example: 123456789 + naam: + description: All relevant info about the patient's name. + type: object + properties: + voornaam: + description: |- + Patient's first name(s), separated by spaces. + It's possible that no first names are known and instead only initials are known; in that case, + the initials are provided with dots (`.`) in between the letters, e.g. `"J.M."`. + type: string + example: Marie Antoinnette + voorvoegsel_achternaam: + description: |- + The prefix of the patient's own last name (what they were born with; not the name inherited from + a spouse): `van`, `de`, `van der` - a mostly uniquely dutch aspect to last names. + type: string + example: de + achternaam: + description: |- + The patient's own last name without a prefix (what they were born with; not the name inherited from + a spouse). + type: string + example: Villepin + voorvoegsel_geslachtsnaam_partner: + description: |- + The prefix of the patient's (ex-)spouse's last name; not all patients that are married go by their spouse's last name and often, if they don't, this field will be blank. + type: string + example: van der + geslachtsnaam_partner: + description: |- + The the patient's (ex-)spouse's last name without prefix; not all patients that are married go by their spouse's last name and often, if they don't, this field will be blank. + type: string + example: Dussen + geslacht: + description: Patient's gender. + type: string + example: man + enum: + - man + - vrouw + - anders + geboortedatum: + description: |- + Patient's birth date. + Note that by convention, patients whose birthdate is unknown pick a date and tend to pick either `xxxx-01-01` or `xxxx-07-01`. Can, in rare cases, be blank - if birth date is not known. + type: string + format: date + example: 1970-07-01 + adres: + description: Patient's address (where they live). + type: object + properties: + straat: + description: Full name of the street; can be blank if not known or not provided, and excludes hous number. + type: string + example: Lange Geer + huisnummer: + description: |- + A combination of house number (digits) and 'house number addition'. If an addition is present, the + entry is formatted as `12 ABC` where the digits representing house number are always at the front, then + a space, then the remainder is the 'house number addition'; if no addition, no space is included. + + A number is always present; possibly 0 to indicate no known house number or the extremely rare case of + a house without a house number. + type: string + example: 4 A + postcode: + description: The post code, in `1234AB` format. If not known, blank. + type: string + example: 2611PV + plaats: + description: The city or town. + type: string + example: Delft + contact: + type: object + properties: + mobiel_telefoonnummer: + description: |- + Patient's mobile number; if not known, a blank string, otherwise, in `+316...` format: A plus, followed by the country code, followed by the phone number. + type: string + example: +316123456789 + vast_telefoonnummer: + description: |- + Patient's landline number; if not known, a blank string, otherwise, in `'+3115...` format: A plus, followed by the country code, followed by the phone number. + type: string + example: +31701234567 + email: + description: |- + Patient's email address. If not known, a blank string. + type: string + example: info@zorgoporde.nl + verzekering: + type: object + properties: + verzekeringsnummer: + description: |- + Patient's insurance registration number. If not known or not insured, a blank string. + type: string + example: 123456789012345 + uzovi: + description: |- + Insurer's identity number in the dutch insurance system (dutch: _UZOVI nummer_). Always + 4 digits exactly, 0-left-padded if needed. If unknown or not insured, 4 zeroes. + type: string + example: 3331 + '401': + $ref: '#/components/responses/NoAuth' + '403': + $ref: '#/components/responses/NoAccess' + '404': + $ref: '#/components/responses/PatNotFound' + /qoc/careprogram: get: tags: @@ -109,8 +244,41 @@ paths: $ref: '#/components/responses/NoAuth' '403': $ref: '#/components/responses/NoAccess' - - + /qoc/indicatorset/{setKey}: + get: + tags: + - QoC + summary: Load an indicator-based report + parameters: + - name: setKey + in: path + description: The key as listed in the `CareProgram` schema. + required: true + schema: + type: string + example: ZEL-dm2 + - name: refDate + in: query + description: |- + The date in `2023-04-01` format; defaults to the first day in the next quarter, e.g. on april 5th 2023, defaults to `2023-07-01`. + required: false + schema: + type: string + format: date + example: 2023-04-01 + responses: + '200': + description: all data required to render an indicatorset is returned + content: + application/json: + schema: + $ref: '#/components/schemas/IndicatorSet' + '401': + $ref: '#/components/responses/NoAuth' + '403': + $ref: '#/components/responses/NoAccess' + '404': + description: The provided `setKey` doesn't refer to a valid program. components: schemas: @@ -163,25 +331,21 @@ components: example: 80.0 default: 100.0 xLow: - description: '*OPTIONAL* If present, draw a bar at this position indicating that this indicator can fall below this lower bound, but if it does, that is noteworthy. For example, because that is beyond 3 standard deviations of the dutch average, or, its a goal set by the practice, the insurer, or the care group and thus falling below it means the goal is not met.' + description: |- + *OPTIONAL* If present, draw a bar at this position indicating that this indicator can fall below this lower bound, but if it does, that is noteworthy. For example, because that is beyond 3 standard deviations of the dutch average, or, its a goal set by the practice, the insurer, or the care group and thus falling below it means the goal is not met. type: number example: 20.0 xHigh: - description: '*OPTIONAL* If present, draw a bar at this position indicating that this indicator can fall above this upper bound, but if it does, that is noteworthy. For example, beyond 3 standard deviations of the dutch average, or, a goal for an indicator where lower is better.' + description: |- + *OPTIONAL* If present, draw a bar at this position indicating that this indicator can fall above this upper bound, but if it does, that is noteworthy. For example, beyond 3 standard deviations of the dutch average, or, a goal for an indicator where lower is better. type: number - example: 80.0 + example: 65.0 unitDesc: - description: '*OPTIONAL* describes the unit that the stated legend values are in, in dutch, and *HTML*. For example, if showing blood pressure, `mmHg`. If missing, treat as the empty string (do not show unit at all)' + description: |- + *OPTIONAL* describes the unit that the stated legend values are in, in dutch, and *HTML*. For example, if showing blood pressure, `mmHg`. If missing, treat as the empty string (do not show unit at all). type: string example: mmHg default: '' - legend: - description: |- - *OPTIONAL* describes the names of each ratio provided. - If not included, do not show a legend - type: array - items: - type: string style: description: |- A key that describes the render style for this entire indicator. @@ -218,6 +382,11 @@ components: - measured - nonPrefMeasured - 'TBD: There are many more.' + legend: + description: |- + *OPTIONAL* If present, render the title of this one bar like a legend for a chart. In dutch, *HTML*, and very short. + type: string + example: '≤ 120' value: description: |- The 'size' of the described ratio. Relative to the range of the bar (as described by `xMax`-`xMin`). @@ -285,3 +454,22 @@ components: description: User is not logged in / session expired. NoAccess: description: User is not allowed to access this API endpoint. + PatNotFound: + description: Provided filter does not match any patients or no medical dossiers are available for this patient. + content: + application/json: + schema: + type: object + properties: + kind: + description: |- + The 'level' of data that isn't available.
+ type: string + example: practice + enum: + - practice + - patient +