API Documentation

API Overview

The Zebrafish Atlas API provides programmatic access to zebrafish microanatomical and gene expression data. This RESTful API allows researchers to query, retrieve, and (with appropriate permissions) contribute to the database.

Base URL

https://zebrafishatlas.example.org/api/v1/

API Versioning

The Zebrafish Atlas API uses versioning to ensure compatibility as the platform evolves. The current version is v1. When a new version is released, previous versions will remain available for a deprecation period of at least 6 months.

Authentication

The Zebrafish Atlas API uses token-based authentication. To use the API, you need to obtain an API token through your account settings.

Obtaining an API Token

1. Log in to your Zebrafish Atlas account
2. Navigate to Account Settings
3. Select the "API Access" tab
4. Click "Generate New Token"
5. Name your token (e.g., "Research Project X") and set an expiration date if desired
6. Store your token securely - it won't be displayed again

Using Your Token

Include your API token in the Authorization header of your HTTP requests:

Authorization: Bearer YOUR_API_TOKEN

Rate Limits

To ensure fair usage and system stability, the Zebrafish Atlas API implements rate limiting:

Rate Limit Headers

Rate limit information is included in the response headers:

• X-Rate-Limit-Limit: The rate limit ceiling for your account type
• X-Rate-Limit-Remaining: The number of requests left for the current time window
• X-Rate-Limit-Reset: The time when the rate limit resets, in Unix time

API Endpoints

The Zebrafish Atlas API is organized into logical resource groups:

Images API

Endpoints for retrieving zebrafish images and associated data:

Metadata API

Endpoints for retrieving metadata about zebrafish images:

Anatomical Structure API

Endpoints for retrieving information about anatomical structures:

Upload API

Endpoints for contributing data to the atlas (requires Researcher or Administrator privileges):

Response Formats

The Zebrafish Atlas API returns data in JSON format by default. Here's an example response from the images endpoint:

{
  "count": 1258,
  "next": "https://zebrafishatlas.example.org/api/v1/images/?limit=20&offset=20",
  "previous": null,
  "results": [
    {
      "id": "bdc5a24e-9f3e-42f1-a53c-6c822a0f7abe",
      "title": "Zebrafish Wildtype - 24hpf - Coronal - 40x",
      "description": "24 hours post fertilization, coronal section",
      "age_type": "24hpf",
      "cut_type": "Coronal",
      "species_category": "Wildtype",
      "file_path": "uploads/24hpf/coronal/24hpf_Coronal_20240410_123456.tif",
      "thumbnail_url": "uploads/24hpf/coronal/thumbnails/24hpf_Coronal_20240410_123456.jpg",
      "segmentation_progress": 75,
      "magnification": "40x",
      "treatment": "",
      "upload_date": "2024-04-10T12:34:56Z",
      "tags": ["24hpf", "coronal", "wildtype"],
      "dimensions": {
        "width": 2048,
        "height": 1536
      }
    },
    // Additional results...
  ]
}

Pagination

List endpoints support pagination to manage large result sets:

• count: Total number of items in the result set
• next: URL to the next page (null if on last page)
• previous: URL to the previous page (null if on first page)
• results: Array of items for the current page

Control pagination with these query parameters:

• limit: Number of items per page (default: 20, max: 100)
• offset: Starting position (default: 0)

Error Handling

The API uses standard HTTP status codes to indicate success or failure. In case of an error, the response will include a JSON object with more details:

Error Response Format

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource could not be found.",
    "details": "Image with ID '123456' does not exist."
  }
}

Common Status Codes

Code Examples

Here are examples of using the Zebrafish Atlas API with common programming languages:

Python Example

import requests
import json

# Configuration
API_BASE_URL = "https://zebrafishatlas.example.org/api/v1"
API_TOKEN = "your_api_token_here"

# Set up headers
headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# Get all 24hpf coronal images
params = {
    "age_type": "24hpf",
    "cut_type": "Coronal",
    "limit": 10
}

response = requests.get(f"{API_BASE_URL}/images/", headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    print(f"Found {data['count']} images")
    
    # Process results
    for image in data["results"]:
        print(f"Image: {image['title']}")
        print(f"  - URL: {image['file_path']}")
        print(f"  - Segmentation: {image['segmentation_progress']}%")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

JavaScript Example

// Configuration
const API_BASE_URL = 'https://zebrafishatlas.example.org/api/v1';
const API_TOKEN = 'your_api_token_here';

// Fetch images for a specific developmental stage
async function fetchImages(ageType, cutType) {
  try {
    const response = await fetch(`${API_BASE_URL}/images/?age_type=${ageType}&cut_type=${cutType}`, {
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      }
    });
    
    if (!response.ok) {
      throw new Error(`API error: ${response.status}`);
    }
    
    const data = await response.json();
    console.log(`Found ${data.count} images for ${ageType} ${cutType}`);
    
    // Process the images
    data.results.forEach(image => {
      console.log(`Image: ${image.title}`);
      console.log(`  - Uploaded: ${new Date(image.upload_date).toLocaleDateString()}`);
      console.log(`  - Progress: ${image.segmentation_progress}%`);
    });
    
    return data;
  } catch (error) {
    console.error('Error fetching images:', error);
    return null;
  }
}

// Example usage
fetchImages('5dpf', 'Sagittal');