Skip to content

UDN Gateway API Client v1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@geocarvalho geocarvalho released this 15 Jul 01:33
· 4 commits to main since this release
v1.0.0
acd5ec7
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

🎉 First Stable Release

This release introduces a complete modernization of the UDN Gateway integration, replacing the legacy script-based approach with a robust, testable, and user-friendly Python package and CLI.

🚀 Major Features

Complete API Client Implementation

  • UDNGatewayClient class with full API coverage for UDN Gateway v2.0
  • Support for all endpoints: participants, sequencing, medical records, consents, evaluations
  • Comprehensive error handling with custom UDNGatewayAPIError exceptions
  • Session management with automatic authentication
  • Robust HTTP request handling with timeouts and retries

Command-Line Interface (CLI)

  • udn_gateway_cli.py - Main entry point for CLI operations
  • udn_gateway/cli.py - Core CLI implementation with argument parsing
  • Multiple operation modes:
    • Participant information retrieval (--info-only)
    • File downloads (all files or filtered by type)
    • GVCF file detection and download (--gvcf)
    • Participant listing (--list-participants)
    • Verbose logging (--verbose)

File Management & Downloads

  • Automatic directory creation for output paths (prevents download failures)
  • Support for downloading files from multiple sources:
    • Sequencing files (with download URL resolution)
    • Medical records
    • Consent documents
    • Wrapup documents
  • File filtering by type and extension
  • Skip existing files to avoid re-downloads
  • Progress logging and error reporting

GVCF File Support

  • Special handling for .gvcf.gz files
  • --gvcf flag for GVCF file detection
  • Combined --gvcf --download for targeted GVCF downloads
  • Automatic file source identification and validation

Utility Functions

  • udn_gateway/utils.py with helper functions:
    • UDN ID validation
    • Directory creation utilities
    • File size formatting
    • JSON data handling
    • Download reporting and summaries

🔧 Technical Improvements

API Integration

  • RESTful API client with proper HTTP session management
  • Automatic URL construction and parameter handling
  • Comprehensive logging for debugging
  • Timeout handling for large file downloads (1-hour timeout)
  • Support for various download URL field names (url, downloadUrl, downloadLink)

Error Handling

  • Custom exception classes for API errors
  • Graceful handling of missing files and network issues
  • Detailed error messages and logging
  • Fallback mechanisms for API failures

Code Organization

  • Modular package structure with __init__.py
  • Clear separation of concerns (client, CLI, utils)
  • Type hints throughout the codebase
  • Comprehensive docstrings and comments

📁 New Package Structure

udn_gateway/
├── init.py # Package initialization and exports
├── client.py # Main API client (335 lines)
├── cli.py # Command-line interface (259 lines)
└── utils.py # Utility functions (222 lines)
udn_gateway_cli.py # CLI entry point
tests/
├── test_cli.py # CLI testing (134 lines)
└── test_sequencing.py # Sequencing data testing (93 lines)

🛠️ Key Fixes & Enhancements

Recent Fixes

  1. Directory Creation Fix - Automatically creates output directories if they don't exist
  2. Download Link Handling - Improved support for various download URL field names
  3. GVCF Download Fix - Corrected GVCF file download logic and filtering
  4. Merge Conflict Resolution - Removed legacy files in favor of new implementation

📋 Usage Examples

Basic Operations

# Get participant information
python udn_gateway_cli.py -a api-key.txt -u UDN287643 --info-only

# Download all files
python udn_gateway_cli.py -a api-key.txt -u UDN287643 --download

# Check for GVCF files
python udn_gateway_cli.py -a api-key.txt -u UDN287643 --gvcf

# Download only GVCF files
python udn_gateway_cli.py -a api-key.txt -u UDN287643 --download --gvcf

# List all participants
python udn_gateway_cli.py -a api-key.txt --list-participants

Programmatic Usage

from udn_gateway import UDNGatewayClient

client = UDNGatewayClient(api_token)
participant_info = client.get_participant("UDN287643")
files = client.get_all_participant_files("UDN287643")

🔄 Migration from Legacy Version

This release represents a complete rewrite and modernization:

  • API v2.0 Support: Full compatibility with the latest UDN Gateway API
  • Python Package: Proper package structure for easy installation and import
  • CLI Interface: User-friendly command-line tools with comprehensive help
  • Error Handling: Robust error handling and recovery mechanisms
  • Documentation: Comprehensive docstrings and usage examples

🧪 Testing

  • CLI Testing: tests/test_cli.py for command-line interface validation
  • Sequencing Testing: tests/test_sequencing.py for API data structure validation
  • Integration Testing: Real API connection testing with sample data

📦 Dependencies

  • requests - HTTP client for API communication
  • argparse - Command-line argument parsing
  • Standard library modules: os, sys, json, logging, subprocess

�� Breaking Changes

  • Removed: Legacy src/request_udn_files.py and src/Dockerfile
  • New: Package-based approach with udn_gateway module
  • Changed: CLI interface completely redesigned for better usability

🔮 Future Enhancements

  • Unit tests for individual components
  • Progress bars for large file downloads
  • Configuration file support
  • Async/await for better performance
  • Additional file format validations
Assets 2
Loading