diff --git a/paths/patient_contactList.yaml b/paths/patient_contactList.yaml index b8f450a..7306913 100644 --- a/paths/patient_contactList.yaml +++ b/paths/patient_contactList.yaml @@ -7,18 +7,41 @@ get: parameters: - name: patUnids in: query + mandatory: true description: |- - A comma separated list of patUnid's. For each patUnid the contact details are in the response. On a query string there is no standardized limit, but in practice the list of unid's might be limited to approximate 512 id's. + A comma separated list of patUnid values, as provided by other API endpoints. + For each patUnid the contact details are in the response. If sending lots of patUnids, we suggest you call this API in a POST (which is also allowed, though the semantic intent of this method is GET: It only queries and makes no changes) to avoid HTTP limits on query length. schema: type: array items: $ref: ../schemas/pat-patUnid.yaml - maxItems: 512 example: "1234,5678" + - name: fields + in: query + mandatory: true + description: |- + Comma separated list of data fields that shold be returned in the response. Available options are: + bsn - adds CSV column/JSON key 'bsn'. + patPubId - adds CSV column/JSON key 'patPubId'. + patUnid - adds CSV column/JSON key 'patUnid'. + gender - adds CSV column/JSON key 'gender', with values 'O', 'M', or 'F'. + displayName - adds CSV column/JSON key 'displayName' with the full name of the patient as one would write it on an envelope. + fullName - adds CSV columns 'initials', 'firstNames', 'infixOwn', 'ownLastName', 'infixPartner', 'partnerLastName', and JSON key 'name' with as value an object with those keys. + addressLine - adds CSV column/JSON key 'addressLine'. + postcode - adds CSV column/JSON key 'postcode'. + city - adds CSV column/JSON key 'city'. + tel - adds CSV column/JSON key 'tel'. + email - adds CSV column/JSON key 'email'. + dob - adds CSV column/JSON key 'dob'. + + See the descriptions in the JSON output section of this documentation for the formatting of these outputs. + example: "displayName,addressLine,postcode,city" - name: Accept in: header description: |- - CSV (RFC 4180) or JSON is responded depending on the preference set by the callers HTTP Accept header. The Accept header is processed according RFC 9110. If one of media-types below has the most weight, then that type will be the content-type of the response. This is always the case when the header equals one of the enumerated types. + This API is capable of emitting both CSV (RFC 4180) and JSON. If a CSV response is needed, ensure mimetype `text/csv` is + mentioned in the `Accept` header at a higher quality than `application/csv`. If no Accept header is provided, the API + responds with JSON. schema: type: string enum: @@ -26,7 +49,8 @@ get: - application/json responses: '200': - description: A patient contact list for (electronic) mailing or phone contact. The list can be responded as CSV or JSON. + description: |- + A patient contact list for (electronic) mailing or phone contact. Per patient only requested details (via `column`) are provided. Any patient that isn't found isn't included in the output. headers: Content-Type: description: The actual content-type of the response. @@ -39,12 +63,16 @@ get: items: type: object properties: - patPubId: - $ref: '../schemas/PatIdentity.yaml#/patPubId' patUnid: $ref: '../schemas/PatIdentity.yaml#/patUnid' + patPubId: + $ref: '../schemas/PatIdentity.yaml#/patPubId' + gender: + $ref: '../schemas/PatIdentity.yaml#/gender' displayName: $ref: '../schemas/pat-Name.yaml#/properties/displayName' + name: + $ref: '../schemas/PatIdentity.yaml#/name' addressLine: description: The concatenation of street, housenumber and -suffix on one line. type: string @@ -56,13 +84,20 @@ get: $ref: '../schemas/PatIdentity.yaml#/contact/properties/tel' email: $ref: '../schemas/PatIdentity.yaml#/contact/properties/email' + bsn: + $ref: '../schemas/PatIdentity.yaml#/bsn' + dob: + $ref: '../schemas/PatIdentity.yaml#/dob' text/csv: schema: type: string + description: |- + An RFC4180 (with comma separator) output, with headers as requested. '400': - description: The request is invalid; for example, it doesn't contain the required `patUnids` parameter. + description: The request is invalid; for example, it doesn't contain the required `patUnids` or `columns` parameter. '401': $ref: '../zoo-api.yaml#/components/responses/JwtFailure' - '404': - $ref: '../zoo-api.yaml#/components/responses/PatNotFound' - \ No newline at end of file + '406': + description: |- + An accept header was sent, but neither `text/csv` nor `application/json` is allowed by it. + As this endpoint can only render its data in those two content types, no response is possible. \ No newline at end of file diff --git a/zoo-api.yaml b/zoo-api.yaml index e9e4989..a412003 100644 --- a/zoo-api.yaml +++ b/zoo-api.yaml @@ -169,6 +169,9 @@ components: items: $ref: schemas/med_dossier/Practitioner.yaml responses: + NotAcceptable: + description: |- + The Accept header as sent by the requestor and the types of content this endpoint can emit have no overlap and thus no response is possible. ReqFailure: description: The request isn't valid; for example, it is missing a required parameter. content: