mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-19 08:12:52 +00:00
feat(labs): add POST /api/labs/fhir-batch for Health Records lab results
The iOS app reads lab results from HealthKit's Health Records and sends them here as FHIR resources, up to 200 per batch. The route maps and writes them with the same mapper and writer as the export import, so a result already imported from an export is a duplicate, sending a batch again is safe, and a deleted result stays deleted. Owner-only (cookie or full-scope login token), its own 60-a-minute bucket, Idempotency-Key supported, per-record status with closed reasons, counts-only audit. The OpenAPI contract documents the route and the source values a lab result can carry, and the import status result names its lab counts.
This commit is contained in:
1 parent
14c3c6696a
commit
376102a71e
8 files changed
+522
-17
No files matched your search
+207
-9
@@ -17416,6 +17416,51 @@ paths:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorEnvelope"
|
||||
"429": *a12
|
||||
/api/labs/fhir-batch:
|
||||
post:
|
||||
tags:
|
||||
- Labs
|
||||
summary: Ingest lab results from Apple Health's Health Records
|
||||
description: "Maps each FHIR lab result (DSTU2 or R4 Observation) to a lab reading and writes it: final results only
|
||||
(`final`, `amended`, `corrected`), the laboratory category, numeric values in their unit (UCUM codes are read),
|
||||
a value with a comparator (`<0.5 mg/L`) kept as text as printed, string and coded values as text, the report's
|
||||
own reference range, and the panel's name for its members. The name resolves to the caller's marker by its own
|
||||
name, an alias, or the catalog analyte its LOINC code names; a new analyte gets a new marker; a reading in
|
||||
another unit is converted when the conversion is known and refused otherwise. The identity is a digest of
|
||||
`sourceURL` and `identifier`, the same one an Apple Health export import builds, so a result already imported
|
||||
from an export is a `duplicate` here, and sending a batch again is safe. First write wins: an amended result
|
||||
under a held identity is a duplicate. Owner-only: a cookie session or a full-scope login token. The body is
|
||||
capped at 1 MiB (413 past it): a client splits a large sync by size as well as by count. Rate limit 60 batches a
|
||||
minute; Idempotency-Key supported. A response carrying `write_failed` is `Cache-Control: no-store` and is not
|
||||
replayed for its key. Audits as `labs.fhir.batch` with counts only."
|
||||
parameters:
|
||||
- *a6
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/FhirLabBatchRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: Batch processed; one result per record. `outcome` reads `inserted` against `failed` (skips and duplicates
|
||||
are information, not failure).
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/FhirLabBatchEnvelope"
|
||||
"401": *a1
|
||||
"403": *a9
|
||||
"409": *a7
|
||||
"422":
|
||||
description: "Nothing was written. `meta.errorCode` = `labs.fhir_batch.invalid`: no records, more than 200, a record
|
||||
without a `resource` object, an over-long HealthKit field, or a field the request does not define (every
|
||||
issue under `details.issues`)."
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorEnvelope"
|
||||
"429": *a5
|
||||
/api/labs/overview:
|
||||
get:
|
||||
tags:
|
||||
@@ -35147,6 +35192,47 @@ components:
|
||||
optional `source` records provenance: `"OCR"` for an on-device-OCR capture (the raw image never reaches the
|
||||
server on this path), defaulting to `"MANUAL"` when omitted. The optional `encounterId` files the reading
|
||||
against a visit the caller owns — always optional, and a link that could not be made never fails the reading.'
|
||||
FhirLabBatchRequest:
|
||||
type: object
|
||||
properties:
|
||||
records:
|
||||
minItems: 1
|
||||
maxItems: 200
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
resource:
|
||||
type: object
|
||||
propertyNames:
|
||||
type: string
|
||||
additionalProperties: {}
|
||||
description: The FHIR resource as JSON (`HKFHIRResource.data`), DSTU2 or R4. Only Observations of the laboratory
|
||||
category are kept.
|
||||
fhirVersion:
|
||||
description: "`HKFHIRResource.fhirVersion` (e.g. `4.0.1`)."
|
||||
type: string
|
||||
maxLength: 16
|
||||
identifier:
|
||||
description: "`HKFHIRResource.identifier`, the resource's id at its source."
|
||||
type: string
|
||||
maxLength: 256
|
||||
sourceURL:
|
||||
description: "`HKFHIRResource.sourceURL`, the issuing institution's FHIR base."
|
||||
type: string
|
||||
maxLength: 2048
|
||||
sourceName:
|
||||
description: The institution as the Health app names it (`sourceRevision.source.name`).
|
||||
type: string
|
||||
maxLength: 200
|
||||
required:
|
||||
- resource
|
||||
required:
|
||||
- records
|
||||
additionalProperties: false
|
||||
description: "1 to 200 Health Records lab results (`HKClinicalTypeIdentifierLabResultRecord`), each the FHIR resource as
|
||||
JSON plus the HealthKit fields its identity is built from. Send a panel and its members in the same batch so the
|
||||
members carry the panel's name. No `userId`: the owner is the caller."
|
||||
UpdateLabResultRequest:
|
||||
type: object
|
||||
properties:
|
||||
@@ -39820,12 +39906,12 @@ components:
|
||||
insights.generate.scopeChanged; labs — labs.biomarker.alias.taken, labs.biomarker.create.invalid,
|
||||
labs.biomarker.duplicate, labs.biomarker.merge.invalid, labs.biomarker.merge.unitMismatch,
|
||||
labs.biomarker.notFound, labs.biomarker.update.invalid, labs.biomarker.update.referenceRangeInvalid,
|
||||
labs.create.invalid, labs.series.invalid, labs.link.invalid, labs.ocr.budgetExceeded,
|
||||
labs.ocr.extractFailed, labs.ocr.fileTooLarge, labs.ocr.fileType, labs.ocr.localOcrDisabled,
|
||||
labs.ocr.outputLimit, labs.ocr.pdfRendererUnavailable, labs.ocr.providerUnsupported,
|
||||
labs.ocr.rateLimited, labs.ocr.tooLarge, labs.restore.invalid, labs.result.notFound, labs.unit.mismatch,
|
||||
labs.update.invalid, labs.update.linkedFieldsImmutable, labs.update.numericExpected,
|
||||
labs.update.qualitativeExpected, labs.update.referenceRangeInvalid,
|
||||
labs.create.invalid, labs.fhir_batch.invalid, labs.series.invalid, labs.link.invalid,
|
||||
labs.ocr.budgetExceeded, labs.ocr.extractFailed, labs.ocr.fileTooLarge, labs.ocr.fileType,
|
||||
labs.ocr.localOcrDisabled, labs.ocr.outputLimit, labs.ocr.pdfRendererUnavailable,
|
||||
labs.ocr.providerUnsupported, labs.ocr.rateLimited, labs.ocr.tooLarge, labs.restore.invalid,
|
||||
labs.result.notFound, labs.unit.mismatch, labs.update.invalid, labs.update.linkedFieldsImmutable,
|
||||
labs.update.numericExpected, labs.update.qualitativeExpected, labs.update.referenceRangeInvalid,
|
||||
labs.update.sourceReferenceRangeInvalid; life_event — life_event.invalid, life_event.not_found;
|
||||
managed_profile — managed_profile.guardian.duplicate, managed_profile.guardian.managed_invitee,
|
||||
managed_profile.guardian.required, managed_profile.handover.no_pending,
|
||||
@@ -44664,6 +44750,12 @@ components:
|
||||
source:
|
||||
type: string
|
||||
minLength: 1
|
||||
externalId:
|
||||
anyOf:
|
||||
- type: string
|
||||
minLength: 1
|
||||
maxLength: 128
|
||||
- type: "null"
|
||||
biomarkerName:
|
||||
type:
|
||||
- string
|
||||
@@ -76677,9 +76769,10 @@ components:
|
||||
type: string
|
||||
additionalProperties: {}
|
||||
- type: "null"
|
||||
description: The worker's outcome summary, null until it finishes. Free-form except for `ecg`, whose five counters
|
||||
(`discovered` / `imported` / `updated` / `skipped` / `failed`) are normalised to bounded non-negative
|
||||
integers before serving.
|
||||
description: "The worker's outcome summary, null until it finishes. Free-form except for `ecg` and `labs`, whose five
|
||||
counters each (`ecg`: `discovered` / `imported` / `updated` / `skipped` / `failed`; `labs`, the lab
|
||||
results from Health Records: `discovered` / `imported` / `duplicate` / `skipped` / `failed`) are
|
||||
normalised to bounded non-negative integers before serving."
|
||||
failureReason:
|
||||
description: Free text on `failed`; null otherwise.
|
||||
type:
|
||||
@@ -77225,6 +77318,9 @@ components:
|
||||
type: string
|
||||
source:
|
||||
type: string
|
||||
description: "Where the reading came from: `MANUAL` (typed), `OCR` (a scanned report), `DOCUMENT` (a document import),
|
||||
`IMPORT` (a lab CSV) or `APPLE_HEALTH` (Apple Health's Health Records, from an export or `POST
|
||||
/api/labs/fhir-batch`). Open-ended: render an unknown value as-is."
|
||||
hasNote:
|
||||
type: boolean
|
||||
rangeStatus:
|
||||
@@ -77319,6 +77415,105 @@ components:
|
||||
- data
|
||||
- error
|
||||
additionalProperties: false
|
||||
FhirLabBatchEnvelope:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
$ref: "#/components/schemas/FhirLabBatchResponse"
|
||||
error:
|
||||
type: "null"
|
||||
meta:
|
||||
type: object
|
||||
properties:
|
||||
requestId:
|
||||
type: string
|
||||
additionalProperties: false
|
||||
required:
|
||||
- data
|
||||
- error
|
||||
additionalProperties: false
|
||||
FhirLabBatchResponse:
|
||||
type: object
|
||||
properties:
|
||||
results:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/FhirLabRecordResult"
|
||||
inserted:
|
||||
type: integer
|
||||
minimum: -9007199254740991
|
||||
maximum: 9007199254740991
|
||||
duplicate:
|
||||
type: integer
|
||||
minimum: -9007199254740991
|
||||
maximum: 9007199254740991
|
||||
skipped:
|
||||
type: integer
|
||||
minimum: -9007199254740991
|
||||
maximum: 9007199254740991
|
||||
failed:
|
||||
type: integer
|
||||
minimum: -9007199254740991
|
||||
maximum: 9007199254740991
|
||||
outcome:
|
||||
type: string
|
||||
enum:
|
||||
- empty
|
||||
- failed
|
||||
- partial
|
||||
- success
|
||||
required:
|
||||
- results
|
||||
- inserted
|
||||
- duplicate
|
||||
- skipped
|
||||
- failed
|
||||
- outcome
|
||||
additionalProperties: false
|
||||
FhirLabRecordResult:
|
||||
type: object
|
||||
properties:
|
||||
index:
|
||||
type: integer
|
||||
minimum: -9007199254740991
|
||||
maximum: 9007199254740991
|
||||
status:
|
||||
type: string
|
||||
enum:
|
||||
- inserted
|
||||
- duplicate
|
||||
- skipped
|
||||
- failed
|
||||
reason:
|
||||
type: string
|
||||
enum:
|
||||
- not_observation
|
||||
- not_lab
|
||||
- not_final
|
||||
- withdrawn
|
||||
- panel_header
|
||||
- no_value
|
||||
- unsupported_value
|
||||
- no_date
|
||||
- future_date
|
||||
- invalid_date
|
||||
- too_large
|
||||
- missing_unit
|
||||
- unit_mismatch
|
||||
- text_too_long
|
||||
- write_failed
|
||||
required:
|
||||
- index
|
||||
- status
|
||||
additionalProperties: false
|
||||
description: "One record's outcome, by its position in the request. `inserted`: written. `duplicate`: the record already
|
||||
holds it, under the same identity (deleted readings included, so a deleted result stays deleted) or as the same
|
||||
reading on the same day from another source. `skipped`: not a reading HealthLog keeps, with `reason`
|
||||
`not_observation` | `not_lab` | `not_final` (preliminary; it is taken once final) | `withdrawn` | `panel_header`
|
||||
| `no_value` | `unsupported_value` | `no_date` | `future_date` | `invalid_date` | `too_large` (a resource over
|
||||
256 KiB). `failed`: a reading that could not be stored, with `reason` `missing_unit` | `unit_mismatch` (the
|
||||
account's marker is in a unit this one does not convert into) | `text_too_long` | `write_failed` (transient:
|
||||
send it again)."
|
||||
LabOverviewEnvelope:
|
||||
type: object
|
||||
properties:
|
||||
@@ -77555,6 +77750,9 @@ components:
|
||||
type: string
|
||||
source:
|
||||
type: string
|
||||
description: "Where the reading came from: `MANUAL` (typed), `OCR` (a scanned report), `DOCUMENT` (a document import),
|
||||
`IMPORT` (a lab CSV) or `APPLE_HEALTH` (Apple Health's Health Records, from an export or `POST
|
||||
/api/labs/fhir-batch`). Open-ended: render an unknown value as-is."
|
||||
rangeStatus:
|
||||
$ref: "#/components/schemas/LabReferenceRangeStatus"
|
||||
createdAt:
|
||||
|
||||
Reference in new issue
Block a user