API Reference Summary

17. API Reference Summary

This page summarizes the route surface exposed by the FastAPI application (api/app.py), organized by the domain module each route delegates to. It is a navigational summary, not a substitute for the generated OpenAPI documentation the reference deployment serves directly.

flowchart TB
    App["api/app.py\n(single composition point)"] --> G1["FHIR Routes\n/fhir/R5/*"]
    App --> G2["CDS Hooks Routes\n/cds-services, /cds-services/{id}"]
    App --> G3["CDSS Routes\n/cdss/evaluate"]
    App --> G4["Meta / Health Routes\n/health, /fhir/R5/metadata"]

    G1 --> FHIR["FHIRStore"]
    G2 --> CDSS["CDSSEngine"]
    G3 --> CDSS
    FHIR --> AUD["AuditChain"]
    CDSS --> AUD

Loading

Figure 15. Route groups exposed by the FastAPI application, all composed at a single point (api/app.py) as established in System Architecture Overview.

17.1 FHIR R5 Routes

All FHIR routes require the X-API-Key header and operate against the in-memory FHIRStore described in The FHIR R5 Interoperability Layer.

Route (indicative)	Behavior
POST /fhir/R5/{resourceType}	Create a resource; validates resourceType consistency, assigns meta.versionId = 1, returns 201 with a weak ETag.
GET /fhir/R5/{resourceType}/{id}	Read a resource by server-assigned ID.
PUT /fhir/R5/{resourceType}/{id}	Update a resource; requires If-Match; returns 409 with an OperationOutcome on version conflict.
DELETE /fhir/R5/{resourceType}/{id}	Delete a resource from the in-memory store.
GET /fhir/R5/{resourceType}	Exact-match search subset over stored resources.
GET /fhir/R5/metadata	Returns a CapabilityStatement generated from the implemented route set.

17.2 CDS Hooks Routes

Described in The Clinical Decision Support Subsystem and positioned against the CDS Hooks specification in Standards and Research Context, Section 2.2.

Route (indicative)	Behavior
GET /cds-services	Discovery endpoint listing available CDS Hooks services.
POST /cds-services/patient-view	Evaluates the RiskScorer rules against the supplied prefetch context and returns CDS Hooks cards with a _medintelos explanation extension.

17.3 CDSS and Health Routes

Route (indicative)	Behavior
POST /cdss/evaluate	Direct evaluation entry point for the scoring pipeline, independent of the CDS Hooks card shape.
GET /health	Liveness check reporting the configured MEDINTELOS_APP_NAME and service status.

17.4 Authentication and Error Shapes

Every route above passes through the single APIKeyAuthenticator dependency described in Security Architecture and Threat Model, Section 9.3, before reaching domain logic. FHIR error responses follow the FHIR OperationOutcome shape; non-FHIR routes return standard FastAPI/Pydantic validation error bodies. Every state-changing call across both route groups appends an entry to the shared AuditChain, as established in The Tamper-Evident Audit Layer.

17.5 Out of Scope for This API

Consistent with the boundary summaries throughout this wiki, the API surface does not include FHIR Bulk Data export, SMART App Launch, subscriptions, or certified CDS Hooks order-select/order-sign flows. Federated learning and consent management are not exposed as HTTP routes at all: the federated coordinator is invoked programmatically by participant sites, and the consent layer is accessed exclusively through the separate Solidity contracts described in Blockchain-Mediated Consent Management.

---

Previous: ← Getting Started · Next: Comparison to Production-Grade Systems →