API Documentation - nazrulworld/fhir-validation-service GitHub Wiki

FHIR Validation Service API Documentation

Overview

The FHIR Validation Service API is a Vert.x-based service with PostgreSQL support for validating FHIR resources and managing Implementation Guides (IGs). This API supports multiple FHIR versions (STU3, R4, R4B, R5) and provides endpoints for health checks, validation, and IG management.

Version: 1.0.0
Base URL: http://localhost:8880 (Local development server)

Endpoints

1. Health Check

GET /health
Operation ID: healthApiHealth
Summary: Get service health status
Description: Check the health status of the service, including the PostgreSQL connection.

Responses

  • 200: Service is healthy
  • 503: Service is unhealthy

2. Kubernetes Liveness Probe

GET /health/liveness
Operation ID: healthApiLiveness
Summary: Kubernetes liveness probe
Description: Simple liveness check for Kubernetes health monitoring.

Responses

  • 200: Service is live
    • Content Type: application/json
    • Schema: 
      {
  "status": "UP",
  "timestamp": 1697051234567
}

3. Validate FHIR Resource

POST /{version}/validate
Operation ID: validationApiValidate
Summary: Validate FHIR resource
Description: Validates a FHIR resource for the specified version.

Parameters

  • Path Parameter:
    • version: Required, FhirVersion (e.g., STU3, R4, R4B, R5)
  • Header Parameters:
    • Content-Type: Optional, defaults to application/json. Supported values: application/json, application/xml, application/fhir+json, application/fhir+xml
    • Accept: Optional, defaults to application/json. Supported values: application/json, application/xml, application/fhir+json, application/fhir+xml

Request Body

  • Required: Yes
  • Content Types:
    • application/json: FHIR resource in JSON format (type: object)
    • application/fhir+json: FHIR resource in JSON format (type: object)
    • application/xml: FHIR resource in XML format (type: string)
    • application/fhir+xml: FHIR resource in XML format (type: string)

Responses

  • 200: Validation results
    • Content Types: application/json, application/fhir+json, application/xml, application/fhir+xml
    • Schema: ValidationResponse
  • 400: Invalid request or validation error

4. Include Implementation Guide

POST /{version}/include-ig
Operation ID: validationApiIncludeIg
Summary: Include Implementation Guide for validation
Description: Includes an Implementation Guide (IG) for validation purposes.

Parameters

  • Path Parameter:
    • version: Required, FhirVersion (e.g., STU3, R4, R4B, R5)

Request Body

  • Required: Yes
  • Content Type: application/json
  • Schema: 
    {
  "igPackageId": "string",
  "igPackageVersion": "string" // defaults to "latest"
}

Responses

  • 200: IG included successfully
    • Content Type: application/json
    • Schema: 
      {
  "status": "success"
}
  • 400: Invalid request or IG not found

5. Register FHIR Profile

POST /{version}/register-profile
Operation ID: profileApiRegisterProfile
Summary: Register a FHIR profile
Description: Registers a FHIR profile for the specified version.

Parameters

  • Path Parameter:
    • version: Required, FhirVersion (e.g., STU3, R4, R4B, R5)

Request Body

  • Required: Yes
  • Content Type: application/json
  • Schema: 
    {
  "url": "string" // URI format
}

Responses

  • 200: Profile registered successfully
    • Content Type: application/json
    • Schema: 
      {
  "status": "success",
  "profileUrl": "string" // URI format
}
  • 400: Invalid request or profile

6. Upload Implementation Guide Package

POST /igs/upload
探索

Operation ID: igPackageApiUploadIg
Summary: Upload and register an Implementation Guide package
Description: Uploads and registers an IG package (max size: 20MB).

Request Body

  • Required: Yes
  • Content Type: multipart/form-data
  • Schema: 
    {
  "file": "binary" // IG package file
}

Responses

7. Register Implementation Guide Package

POST /igs/register
Operation ID: igPackageApiRegisterIg
Summary: Register an Implementation Guide package
Description: Registers an IG package by providing a download URL.

Request Body

  • Required: Yes
  • Content Type: application/json
  • Schema: 
    {
  "downloadUrl": "string", // URI format
  "name": "string",
  "version": "string", // defaults to "latest"
  "includeDependency": true // defaults to true
}

Responses

8. Get IG Package Dependencies

GET /igs/{name}/{version}/dependencies
Operation ID: igPackageApiGetDependenciesGraph
Summary: Get IG package dependencies
Description: Retrieves the dependency graph for a specified IG package.

Parameters

  • Path Parameters:
    • name: Required, type: string
    • version: Required, type: string

Responses

  • 200: Dependencies retrieved successfully
    • Content Type: application/json
    • Schema: type: object
  • 404: Package not found

9. Get IG Package Conformance Report

GET /igs/{name}/{version}/conformance
Operation ID: igPackageApiGenerateConformanceReport
Summary: Get IG package conformance report
Description: Generates a conformance report for a specified IG package.

Parameters

  • Path Parameters:
    • name: Required, type: string
    • version: Required, type: string

Responses

  • 200: Conformance report generated successfully
    • Content Type: application/json
    • Schema: type: object
  • 500: Error generating report

Schemas

FhirVersion

  • Type: string
  • Enum: STU3, R4, R4B, R5
  • Description: Supported FHIR versions

HealthResponse

{
  "status": "string", // UP or DOWN
  "timestamp": "integer", // int64
  "postgres": {
    "status": "string", // UP or DOWN
    "responseTime": "integer", // int64
    "error": "string"
  },
  "error": "string"
}

ValidationResponse

{
  "valid": "boolean",
  "messages": [
    {
      "severity": "string",
      "location": "string",
      "message": "string"
    }
  ]
}

IgRegistrationResponse

{
  "status": "success",
  "name": "string",
  "version": "string"
}

ErrorResponseStandard

{
  "status": "error",
  "error": "string"
}

ValidationErrorResponse

{
  "valid": "boolean",
  "errors": [
    {
      "severity": "string", // FATAL, ERROR, INFORMATION
      "location": "string",
      "message": "string"
    }
  ]
}