FHIRPath Lab API server

[johngrimes]

Implement a Python-based HTTP server that exposes Pathling's FHIRPath execution capabilities to FHIRPath Lab, enabling interactive FHIRPath expression evaluation and debugging through the FHIRPath Lab web interface.

Background

FHIRPath Lab is a web-based tool for experimenting with FHIRPath expressions across different FHIRPath engines. It requires server-side APIs for engines that cannot run in the browser. This issue tracks the implementation of a Pathling-based backend for FHIRPath Lab.

Requirements

API specification

The API must conform to the FHIRPath Lab server API specification:

• Accept FHIR Parameters resources as input
• Return FHIR Parameters resources as output
• Support the POST /$fhirpath-r4 endpoint
• Support CORS to allow for requests originating from FHIRPath Lab domains

Core functionality

1. Execute FHIRPath expressions over arbitrary data

   • Similar to the SQL-on-FHIR test runner capability
   • Not limited to FHIR resources - should handle any JSON data
   • Support for context expressions to establish evaluation scope

2. Input parameters (via FHIR Parameters resource):

   • expression (required): The FHIRPath expression to execute
   • resource (required): The data to execute against
   • context (optional): Context expression to establish scope
   • variables (optional): Environment variables for the expression
   • validate (optional): Validate expression before execution
   • terminologyServer (optional): Terminology server URL for lookups

3. Output parameters (via FHIR Parameters resource):

   • parameters part containing:
     • evaluator: Engine name and version (e.g., "Pathling 8.1.0")
     • expression: The executed expression
     • context: The context used (if any)
     • resource: The input resource
     • variables: The variables passed (if any)
     • parseDebugTree: Abstract Syntax Tree as JSON
     • expectedReturnType: Static analysis of return type
   • result parts containing execution results for each context iteration
   • Support for trace output from trace() function calls

4. Result format:

   • Each result should include the datatype as the part name
   • Support for primitive types, resource types, and complex types
   • Use the http://fhir.forms-lab.com/StructureDefinition/json-value extension for values that cannot be represented as FHIR Parameters (e.g., backbone elements)

Library API enhancements

Expand the Pathling library API to support:

1. Execution of individual FHIRPath expressions independent of FHIR resources
2. Evaluation over arbitrary JSON data structures
3. Access to expression parsing and type analysis information
4. Support for FHIRPath variables and context expressions

Architecture

1. Implementation: Python web server (Flask or FastAPI)
2. Dependencies: Pathling Python library only
3. Versioning: Semantic versioning, separate from other Pathling modules
4. Location: New directory at the repository root (e.g., fhirpath-lab-api/)

Deployment

Provide AWS deployment infrastructure using CDK to enable cost-efficient hosting with acceptable user experience for FHIRPath Lab users.

Deployment options to investigate:

1. AWS Lambda + Function URL: Pay-per-request pricing, zero cost when idle, cold start considerations
2. AWS Lambda + HTTP API Gateway: Custom domain support, advanced routing capabilities
3. AWS Lambda + Application Load Balancer: Reduced cold starts with health checks, minimum monthly cost
4. ECS Fargate + Application Load Balancer: No cold starts, always-on costs
5. AWS App Runner: Managed platform with auto-scaling

Key considerations:

• Cold start impact on user experience
• Cost efficiency for intermittent usage patterns
• Deployment complexity
• Pathling library size and memory requirements
• Performance requirements for FHIRPath Lab integration

Deployment artifacts should include:

• CDK stack for infrastructure as code
• GitHub Actions workflow for CI/CD
• Configuration for multiple environments (dev/staging/prod)
• Documentation for deployment and monitoring

Reference implementation

The JavaScript reference implementation provides a good example of the expected API behaviour:

• Repository: https://github.com/brianpos/fhirpath-lab-fhirpath-js-api
• Key features to replicate:
  • Expression parsing and AST generation
  • Debug tracing with execution traces
  • Variable substitution and escape sequence handling
  • Comprehensive error handling with FHIR OperationOutcome responses

Acceptance criteria

• Python server application created with separate versioning
• Library API extended to support arbitrary data evaluation
• POST endpoint implementing FHIRPath Lab specification
• Support for all required input parameters
• Output includes evaluator identification, results, and metadata
• Configurable CORS
• Error handling returns FHIR OperationOutcome resources
• Documentation for running and deploying the server
• Example requests/responses in README
• AWS CDK stack for chosen deployment option
• GitHub Actions workflow for automated deployment
• Documentation for deployment and monitoring