API for the Exchange of Medicinal Product Information (APIX), published by Gravitate Health Project. This guide is not an authorized publication; it is the continuous build for version 0.1.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/APIX---API-Exchange-for-Medicinal-Products/ and changes regularly. See the Directory of published versions

Architecture

Component	Minimum Requirement	Recommendation / Examples
FHIR Server (Regulatory Authority and Submitting Company)	FHIR R5, conditional create/update, Subscriptions, SMART Backend Services	Open-source or commercial servers such as HAPI FHIR, Smile CDR, Microsoft Azure API for FHIR, AWS HealthLake, Google Cloud Healthcare API, or any other compliant FHIR server
Authentication	SMART Backend Services (system-level scopes, JWT bearer tokens)	Mandatory for production use
Subscriptions	R5-native or R5 backport, rest-hook channel with signed webhook delivery	Mandatory for production environments
Validation Engine	Support for $validate operation + custom regulatory rules Operation	May be implemented as part of the FHIR server, an API gateway, or a dedicated validation service
Audit	Provenance resource created/updated on every relevant Task change	Mandatory
Search / Grouping	Support for groupIdentifier, partOf, chaining, and reverse chaining as required by the profiles	Essential for workflow navigation and reporting

System Landscape

The following interaction diagram illustrates how these components work together in a production environment:

sequenceDiagram
    autonumber
    participant App as Applicant (RIM System)
    participant Auth as Auth Server (OAuth2)
    participant APIX as APIX FHIR Server
    participant Val as Validation Engine

    note over App, Val: Phase 1: Authentication & Submission
    
    App->>Auth: 1. Request Access Token
    Auth-->>App: 2. Return JWT (Scope: system/Task.cruds)
    
    App->>APIX: 3. POST /Task (Submission Bundle)
    APIX->>Val: 4. $validate Bundle
    Val-->>APIX: 5. Validation Outcome (Pass)
    APIX-->>App: 6. 201 Created (Task.status = received)

    note over App, Val: Phase 2: Asynchronous Processing & Notification

    APIX->>APIX: 7. Regulator Review (Status Change)
    
    par Real-Time Notification
        APIX->>App: 8. POST Subscription Notification (Task.status = in-progress)
    and Audit Logging
        APIX->>APIX: 9. Create Provenance Record
    end

Data Governance and Security

The APIX "Index Pattern" relies on a logical separation of data rather than physical silos. This approach ensures scalability while maintaining strict intellectual property (IP) protection.

Logical Data Separation (Multi-Tenancy)

In a shared regulatory environment, data for different medicinal products (e.g., Drug A vs. Drug B) sits in a common storage layer but is differentiated by FHIR metadata:

• Subject Linking: Every DocumentReference is linked to a specific MedicinalProductDefinition via the subject field, ensuring documents are contextually tied to the correct product lifecycle.
• Metadata Categorization: The category and type fields (using CTD Module and Section codes) provide the structural hierarchy needed to organize large submissions within the product context.
• Shared Infrastructure: While physical separation (e.g., dedicated database instances per company) is an implementation choice, the APIX standard is designed to work in a multi-tenant environment where metadata-driven filters provide the necessary isolation.

IP Protection and Access Control

To protect company trade secrets and clinical data, the following security principles are applied:

1. SMART on FHIR & OAuth2: All access is authenticated via system-level or user-level JWT tokens. These tokens carry claims about the user's organizational affiliation (e.g., Org: SynthPharma).
2. Attribute-Based Access Control (ABAC): The regulator's FHIR server acts as a Policy Enforcement Point. Every query is intercepted to ensure that a company can only search for or retrieve resources that "belong" to their organizational compartment.
3. Security Labels: The DocumentReference.securityLabel field allows for granular confidentiality tagging (e.g., R for Restricted). Access is denied unless the requester’s security clearance matches the document's label.
4. Provenance & Integrity: Every upload is tracked via a Provenance resource, providing a cryptographic audit trail that proves the origin and integrity of the submission, ensuring no unauthorized party has modified or accessed the index.

Binary Upload Guide (Post-then-Link)

To handle large documents (e.g., 20MB PDFs) or massive data packages (e.g., 50GB stability datasets) without impacting API performance, APIX utilizes a two-step "Post-then-Link" mechanism.

Step 1: Upload Raw Binary

The submittor posts the file as a raw octet-stream directly to the /Binary endpoint. This avoids the overhead of Base64 encoding.

• Request: POST [base]/Binary
• Header: Content-Type: application/pdf (or appropriate MIME type)
• Body: Raw binary bytes.
• Response: 201 Created with a Location header (e.g., Location: Binary/123).

Step 2: Create Metadata Link (DocumentReference)

The submittor creates a DocumentReference resource that "claims" the binary and provides regulatory context (CTD section, title, etc.).

• Content URL: Set DocumentReference.content.attachment.url to the ID received in Step 1 (Binary/123).
• Metadata: Add category (e.g., Module 3) and type (e.g., Stability Report) to allow for indexing and search.

Step 3: Orchestrate via Task

The DocumentReference ID is added to the Task.input or Task.output array. The regulator can now discover the file through the Task and only retrieve the binary payload if needed.

Technical Benefits

• Memory Efficiency: The server can stream the binary directly to storage without loading the entire file into memory.
• Scalability: Supports massive files that would otherwise exceed JSON size limits.
• Resume-ability: If an upload is interrupted, only the specific Binary needs to be retried, not the entire submission package.