openapi: 3.1.0
info:
  title: APEX FHIR Data Lake API
  version: 1.0.0
  summary: Longitudinal FHIR store — HAPI R4, ingest, quality, lineage, and GPID master search
  description: |
    OpenAPI contract for the **Apex FHIR Data Lake** — Parker Apex's GPID-centered longitudinal clinical store.

    The lake has two public surfaces:

    1. **`lake.parkerapex.com`** — HAPI FHIR R4 REST API (read/write/search, bulk `$export`). Primary store for
       resources synced from Nexus, CMS partners, Beacon, Prime, and Pulse outboxes.

    2. **`app.lake.parkerapex.com`** — Lake administration & analytics API (FastAPI): FHIR ingest pipeline,
       data quality metrics, lineage tracking, dataset catalog, and GPID master search.

    Authentication: Plexus OAuth bearer tokens (`HAPI_FHIR_AUTH_MODE=oauth_only` in production). Service
    integrations may use `X-Apex-Service-Key` on ingest boundaries. All writes must include GPID and tenant
    instance tags per the [lake contract](https://developers.parkerapex.com/lake).

    Source repo: [apex-data-lake](https://github.com/ParkerApex/apex-data-lake) (HAPI deploy + lake-first APIs).
servers:
  - url: https://lake.parkerapex.com/fhir/R4
    description: HAPI FHIR R4 (production lake)
  - url: https://app.lake.parkerapex.com/api
    description: Lake admin & pipeline API
  - url: https://sandbox.lake.parkerapex.com/fhir/R4
    description: Sandbox FHIR (when provisioned)
tags:
  - name: FHIR R4
  - name: Bulk Export
  - name: Ingest
  - name: Quality
  - name: Lineage
  - name: GPID Master
  - name: Datasets
security:
  - OAuth2: []
paths:
  /metadata:
    get:
      tags: [FHIR R4]
      operationId: lakeFhirMetadata
      summary: HAPI FHIR CapabilityStatement
      servers:
        - url: https://lake.parkerapex.com/fhir/R4
      security: []
      responses:
        '200':
          description: CapabilityStatement
  /Patient:
    get:
      tags: [FHIR R4]
      operationId: lakeSearchPatients
      summary: Search Patient resources in the lake
      servers:
        - url: https://lake.parkerapex.com/fhir/R4
      security:
        - OAuth2: [lake.fhir.read]
      parameters:
        - name: identifier
          in: query
          required: true
          schema:
            type: string
          description: GPID identifier — `https://parkerapex.com/fhir/identifier/gpid|{gpid}`
        - name: _tag
          in: query
          schema:
            type: string
          description: Tenant tag filter (`https://parkerapex.com/fhir/tag/tenant|{instance_id}`)
      responses:
        '200':
          description: FHIR Bundle
    post:
      tags: [FHIR R4]
      operationId: lakeCreatePatient
      summary: Create Patient in HAPI lake
      servers:
        - url: https://lake.parkerapex.com/fhir/R4
      security:
        - OAuth2: [lake.fhir.write]
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
      responses:
        '201':
          description: Patient created
  /$export:
    get:
      tags: [Bulk Export]
      operationId: lakeBulkExport
      summary: Bulk NDJSON export from lake
      servers:
        - url: https://lake.parkerapex.com/fhir/R4
      security:
        - OAuth2: [lake.fhir.read]
      parameters:
        - name: _type
          in: query
          schema:
            type: string
        - name: _since
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '202':
          description: Export job started
  /fhir/ingest:
    post:
      tags: [Ingest]
      operationId: lakeFhirIngest
      summary: Ingest FHIR Bundle into lake pipeline
      description: Validates resources, applies GPID + tenant contract, writes to BigQuery staging and HAPI.
      servers:
        - url: https://app.lake.parkerapex.com/api
      security:
        - OAuth2: [lake.ingest.write]
      parameters:
        - name: X-Apex-Tenant-Id
          in: header
          required: true
          schema:
            type: string
        - name: X-Purpose-Of-Use
          in: header
          schema:
            type: string
            enum: [treatment, payment, operations, research, audit, public_health]
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
              description: FHIR transaction or collection Bundle
      responses:
        '202':
          description: Ingest accepted
        '400':
          description: Contract validation failed
  /quality:
    get:
      tags: [Quality]
      operationId: lakeQualityMetrics
      summary: Data quality metrics by layer
      servers:
        - url: https://app.lake.parkerapex.com/api
      security:
        - OAuth2: [lake.quality.read]
      parameters:
        - name: tenant_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Quality scores — completeness, timeliness, conformance
  /lineage/{resource_id}:
    get:
      tags: [Lineage]
      operationId: lakeResourceLineage
      summary: Provenance and lineage for a lake resource
      servers:
        - url: https://app.lake.parkerapex.com/api
      security:
        - OAuth2: [lake.lineage.read]
      parameters:
        - name: resource_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Lineage graph nodes and edges
  /overview:
    get:
      tags: [Quality]
      operationId: lakePlatformOverview
      summary: Lake platform overview
      description: Total resources, storage, layer statistics, CDC lag, freshness.
      servers:
        - url: https://app.lake.parkerapex.com/api
      security:
        - OAuth2: [lake.quality.read]
      responses:
        '200':
          description: Overview metrics
  /datasets:
    get:
      tags: [Datasets]
      operationId: lakeListDatasets
      summary: Curated dataset catalog
      servers:
        - url: https://app.lake.parkerapex.com/api
      security:
        - OAuth2: [lake.datasets.read]
      responses:
        '200':
          description: Dataset list with schema versions
  /gpid-master/search:
    post:
      tags: [GPID Master]
      operationId: lakeGpidMasterSearch
      summary: GPID master index search
      servers:
        - url: https://app.lake.parkerapex.com/api
      security:
        - OAuth2: [lake.gpid.read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                gpid:
                  type: string
                given_name:
                  type: string
                family_name:
                  type: string
                birth_date:
                  type: string
                  format: date
      responses:
        '200':
          description: GPID master matches
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.parkerapex.com/oauth/token
          scopes:
            lake.fhir.read: Read FHIR resources from HAPI lake
            lake.fhir.write: Write FHIR resources to HAPI lake
            lake.ingest.write: Submit bundles to ingest pipeline
            lake.quality.read: Quality and overview metrics
            lake.lineage.read: Resource lineage
            lake.datasets.read: Curated dataset catalog
            lake.gpid.read: GPID master search
