173 lines
4.2 KiB
Markdown
173 lines
4.2 KiB
Markdown
# DICOM Migration REST API
|
|
|
|
This REST API provides an endpoint to trigger DICOM study migration for a specific Accession Number.
|
|
|
|
## Features
|
|
|
|
- Migrate DICOM studies by Accession Number
|
|
- Token-based authentication
|
|
- Detailed JSON responses with operation status
|
|
- Proper logging and error handling
|
|
- Automatic cleanup of DICOM files after each request
|
|
|
|
## Requirements
|
|
|
|
- Python 3.9 or higher
|
|
- FastAPI
|
|
- Uvicorn
|
|
- Dependencies from the main DICOM migration project
|
|
|
|
## Installation
|
|
|
|
1. Install the required dependencies:
|
|
|
|
```bash
|
|
cd api-app
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The API uses the same configuration settings as the main DICOM migration project.
|
|
|
|
### Authentication
|
|
|
|
The API uses token-based authentication. Set your token using the environment variable:
|
|
|
|
```bash
|
|
export API_TOKEN=your-secure-token
|
|
```
|
|
|
|
If no token is provided, a default token will be used (not recommended for production).
|
|
|
|
## Usage
|
|
|
|
### Starting the API Server
|
|
|
|
```bash
|
|
# Start the server on default port 8000
|
|
python run.py
|
|
|
|
# Specify a custom port
|
|
python run.py --port 9000
|
|
|
|
# Specify a custom token
|
|
python run.py --token your-secure-token
|
|
|
|
# Enable auto-reload for development
|
|
python run.py --reload
|
|
```
|
|
|
|
### API Endpoints
|
|
|
|
#### 1. Migrate Study by Accession Number
|
|
|
|
```
|
|
POST /migrate/{accession_number}
|
|
```
|
|
|
|
**Authentication:**
|
|
- Bearer token in Authorization header
|
|
|
|
**Response:**
|
|
|
|
Successful migration:
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "Successfully migrated study for accession number: ABC12345",
|
|
"details": {
|
|
"study_uid": "1.2.826.0.1.3680043.9.7307.1.123456",
|
|
"his_integration_success": true
|
|
}
|
|
}
|
|
```
|
|
|
|
Failed migration:
|
|
```json
|
|
{
|
|
"success": false,
|
|
"message": "Failed to process study: Study not found",
|
|
"details": null
|
|
}
|
|
```
|
|
|
|
## Example API Calls
|
|
|
|
### Using curl
|
|
|
|
```bash
|
|
# Migrate a study by accession number
|
|
curl -X POST "http://localhost:8000/migrate/ABC12345" \
|
|
-H "Authorization: Bearer your-token" \
|
|
-H "Content-Type: application/json"
|
|
```
|
|
|
|
### Using Python requests
|
|
|
|
```python
|
|
import requests
|
|
|
|
url = "http://localhost:8000/migrate/ABC12345"
|
|
headers = {
|
|
"Authorization": "Bearer your-token",
|
|
"Content-Type": "application/json"
|
|
}
|
|
|
|
response = requests.post(url, headers=headers)
|
|
print(response.json())
|
|
```
|
|
|
|
## Logs
|
|
|
|
The API logs are stored in the `logs/api.log` file. The log includes information about:
|
|
|
|
- API startup and shutdown
|
|
- Migration requests
|
|
- Errors during migration process
|
|
- Integration with HIS results
|
|
|
|
## Troubleshooting
|
|
|
|
1. **Authentication Error**:
|
|
- Make sure you're providing the correct token in the Authorization header
|
|
- Check that the token format is `Bearer your-token`
|
|
|
|
2. **Study Not Found**:
|
|
- Verify that the accession number is correct
|
|
- Check if the PACS server is reachable
|
|
- Verify that the study exists in the source PACS
|
|
|
|
3. **Connection Error**:
|
|
- Check PACS connectivity
|
|
- Verify network settings in `config/settings.py`
|
|
|
|
## Integrating with External Systems
|
|
|
|
You can call this API from other systems to trigger DICOM migrations for specific studies:
|
|
|
|
1. Obtain the API token
|
|
2. Make a POST request to `/migrate/{accession_number}`
|
|
3. Handle the JSON response based on the `success` field
|
|
|
|
## Technical Details
|
|
|
|
### DICOM File Cleanup
|
|
|
|
The API implements a robust cleanup mechanism to ensure that DICOM files are always removed after processing:
|
|
|
|
1. **Exit Handlers**: The application registers cleanup handlers via Python's `atexit` module and signal handlers for graceful cleanup during server shutdown.
|
|
|
|
2. **Per-Request Cleanup**: After each migration request completes (whether successful or not), the API explicitly calls the cleanup function to remove all DICOM files associated with the study.
|
|
|
|
3. **Directory Registration**: All temporary directories created during the migration process are registered for cleanup, ensuring no files are left behind.
|
|
|
|
This dual approach (exit handlers + explicit cleanup) ensures that:
|
|
- DICOM files are immediately removed after each API request completes
|
|
- No files are left behind even if the server crashes or is terminated abnormally
|
|
- Disk space is efficiently managed during high-volume operations
|
|
|
|
### Authentication
|
|
|
|
The API uses Bearer token authentication. The token is specified through:
|