<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

# Backend Services Reference Overview

BioMCP integrates with multiple biomedical databases and services to provide comprehensive research capabilities. This reference documents the underlying APIs and their capabilities.

## Service Categories

### Literature and Publications

- **[PubTator3](06-pubtator3.md)**: Biomedical literature with entity annotations
- **Europe PMC**: Preprints from bioRxiv and medRxiv

### Clinical Trials

- **[ClinicalTrials.gov](04-clinicaltrials-gov.md)**: U.S. and international clinical trials registry
- **[NCI CTS API](05-nci-cts-api.md)**: National Cancer Institute's enhanced trial search

### Biomedical Annotations

- **[BioThings Suite](02-biothings-suite.md)**:
  - MyGene.info - Gene annotations
  - MyVariant.info - Variant annotations
  - MyDisease.info - Disease ontology
  - MyChem.info - Drug/chemical data

### Cancer Genomics

- **[cBioPortal](03-cbioportal.md)**: Cancer genomics portal with mutation data
- **TCGA**: The Cancer Genome Atlas (via MyVariant.info)

### Variant Effect Prediction

- **[AlphaGenome](07-alphagenome.md)**: Google DeepMind's AI for regulatory predictions

## API Authentication

| Service            | Authentication Required | Type    | Rate Limits         |
| ------------------ | ----------------------- | ------- | ------------------- |
| PubTator3          | No                      | Public  | 3 requests/second   |
| ClinicalTrials.gov | No                      | Public  | 50,000 requests/day |
| NCI CTS API        | Yes                     | API Key | 1,000 requests/day  |
| BioThings APIs     | No                      | Public  | 1,000 requests/hour |
| cBioPortal         | Optional                | Token   | Higher with token   |
| AlphaGenome        | Yes                     | API Key | Contact provider    |

## Data Flow Architecture

```
User Query → BioMCP Tools → Backend APIs → Unified Response

Example Flow:
1. User: "Find articles about BRAF mutations"
2. BioMCP: article_searcher tool
3. APIs Called:
   - PubTator3 (articles)
   - cBioPortal (mutation data)
   - Europe PMC (preprints)
4. Response: Integrated results with citations
```

## Service Reliability

### Primary Services

- **PubTator3**: 99.9% uptime, updated daily
- **ClinicalTrials.gov**: 99.5% uptime, updated daily
- **BioThings APIs**: 99.9% uptime, real-time data

### Fallback Strategies

- Cache frequently accessed data
- Implement exponential backoff
- Use alternative endpoints when available

## Common Integration Patterns

### 1. Entity Recognition Enhancement

```
PubTator3 → Extract entities → BioThings → Get detailed annotations
```

### 2. Variant to Trial Pipeline

```
MyVariant.info → Get gene → ClinicalTrials.gov → Find relevant trials
```

### 3. Comprehensive Gene Analysis

```
MyGene.info → Basic info
cBioPortal → Cancer mutations
PubTator3 → Literature
AlphaGenome → Predictions
```

## Performance Considerations

### Response Times (typical)

- PubTator3: 200-500ms
- ClinicalTrials.gov: 300-800ms
- BioThings APIs: 100-300ms
- cBioPortal: 200-600ms
- AlphaGenome: 1-3 seconds

### Optimization Strategies

1. **Batch requests** when APIs support it
2. **Cache static data** (gene names, ontologies)
3. **Parallelize independent** API calls
4. **Use pagination** for large result sets

## Error Handling

### Common Error Types

- **Rate Limiting**: 429 errors, implement backoff
- **Invalid Parameters**: 400 errors, validate inputs
- **Service Unavailable**: 503 errors, retry with delay
- **Authentication**: 401 errors, check API keys

### Error Response Format

```json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "retry_after": 3600
  }
}
```

## Data Formats

### Input Formats

- **Identifiers**: HGNC symbols, rsIDs, NCT numbers, PMIDs
- **Coordinates**: GRCh38 genomic positions
- **Terms**: MeSH, MONDO, HPO ontologies

### Output Formats

- **JSON**: Primary format for all APIs
- **XML**: Available for some services
- **TSV/CSV**: Export options for bulk data

## Update Frequencies

| Service            | Update Frequency | Data Lag   |
| ------------------ | ---------------- | ---------- |
| PubTator3          | Daily            | 1-2 days   |
| ClinicalTrials.gov | Daily            | Real-time  |
| NCI CTS            | Daily            | 1 day      |
| BioThings          | Real-time        | Minutes    |
| cBioPortal         | Quarterly        | 3-6 months |

## Best Practices

### 1. API Key Management

- Store keys securely
- Rotate keys periodically
- Monitor usage against limits

### 2. Error Recovery

- Implement retry logic
- Log failed requests
- Provide fallback data

### 3. Data Validation

- Verify gene symbols
- Validate genomic coordinates
- Check identifier formats

### 4. Performance

- Cache when appropriate
- Batch similar requests
- Use appropriate page sizes

## Getting Started

1. Review individual service documentation
2. Obtain necessary API keys
3. Test endpoints with sample data
4. Implement error handling
5. Monitor usage and performance

## Support Resources

- **PubTator3**: [Support Forum](https://www.ncbi.nlm.nih.gov/research/pubtator3/)
- **ClinicalTrials.gov**: [Help Desk](https://clinicaltrials.gov/help)
- **BioThings**: [Documentation](https://docs.biothings.io/)
- **cBioPortal**: [User Guide](https://docs.cbioportal.org/)
- **NCI**: [API Support](https://api.cancer.gov/support)


<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->