Best Practices for Using the VerseDB API

Cache Your Requests

If you're requesting the same data frequently (like publishers, series, or character details), cache the results on your end. This reduces unnecessary API calls and helps you stay within your hourly rate limit.

What to cache:

• Publisher data (changes infrequently)
• Series/volume details (mostly static)
• Character and creator profiles (rarely updated)
• Story arc information (stable data)

What NOT to cache:

• User collection/wishlist (personal data changes often)
• Pull list (updated weekly with new releases)
• Shop inventory (real-time stock levels)

Use Bulk Endpoints When Available

Currently, the VerseDB API supports standard CRUD operations per resource. When adding or updating multiple items:

For collections:

POST /api/collections/{id}/items    # Add single item
DELETE /api/collections/{collection_id}/items/{item_id}  # Remove single item

For wishlists:

POST /api/wishlists/{id}/items      # Add single item
DELETE /api/wishlists/{wishlist_id}/items/{item_id}  # Remove single item

Best practice: If you need to add multiple items, batch your requests with a small delay between them (100-200ms) to avoid rate limiting.

Monitor Rate Limit Headers

Every API response includes rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1712869200

Track these in your code:

const checkRateLimit = (response) => {
  const remaining = response.headers.get('X-RateLimit-Remaining');
  const reset = response.headers.get('X-RateLimit-Reset');
  
  if (remaining < 50) {
    console.warn(`Only ${remaining} requests remaining`);
  }
  
  if (remaining < 10) {
    const resetDate = new Date(reset * 1000);
    console.warn(`Rate limit low! Resets at ${resetDate}`);
  }
};

Handle 429 Responses Gracefully

When you exceed your rate limit, you'll receive a 429 Too Many Requests response. Never continue hammering the API.

Implement exponential backoff:

async function apiRequestWithRetry(url, options = {}, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
      console.log(`Rate limited. Waiting ${retryAfter}s before retry ${attempt + 1}`);
      await sleep(retryAfter * 1000);
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

Use Proper Authentication

For personal data endpoints (collections, wishlists, pull lists), authentication is required:

fetch('https://versedb.com/api/user/collections', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE',
    'Content-Type': 'application/json'
  }
})

Public endpoints (series, issues, characters) don't require authentication:

// No auth needed for public data
fetch('https://versedb.com/api/series/123')

Leverage Search Endpoints Efficiently

Search endpoints have stricter rate limits. Use them wisely:

Available search endpoints:

GET /api/creators/search?q=stan+lee
GET /api/characters/search?q=spider-man

Best practices:

• Implement debouncing for user input (wait 300ms after typing stops)
• Cache search results for common queries
• Use specific filters when available to reduce result size
• Limit search frequency in your UI

Use Nested Routes for Related Data

The API provides nested routes to efficiently fetch related data:

GET /api/series/{id}/story-arcs       # Get story arcs for a series
GET /api/titles/{id}/story-arcs       # Get story arcs for a title
GET /api/issues/{id}/story-arcs       # Get story arcs for an issue
GET /api/issues/{id}/variants         # Get variants for an issue
GET /api/publishers/{id}/story-arcs   # Get story arcs by publisher

Better than: Fetching full story arc list and filtering client-side.

Optimize Issue Variant Requests

When working with issue variants:

GET /api/issues/{issue}/variants               # List all variants
GET /api/issues/{issue}/variants/{variant}     # Get specific variant

For authenticated users (managing variants):

POST /api/issues/{issue}/variants              # Create variant
PUT /api/issues/{issue}/variants/{variant}     # Update variant
DELETE /api/issues/{issue}/variants/{variant}  # Delete variant

Shop Locator API Best Practices

If you're using the comic shop locator features:

Public discovery (no auth):

GET /api/shops                        # Browse shops
GET /api/shops/{shop}                 # Shop details
GET /api/shops/{shop}/inventory       # Available issues
GET /api/issues/{issue}/shops         # Find shops with specific issue
GET /api/inventory/search             # Search across all shop inventories

Authenticated shop management:

POST /api/shops/{shop}/claim          # Claim shop ownership
PUT /api/shops/{shop}                 # Update shop details
POST /api/shops/{shop}/inventory      # Add inventory
POST /api/shops/{shop}/favorite       # Favorite a shop
GET /api/user/favorite-shops          # Your favorite shops

Don't Share or Leak Your Token

Security checklist:

• ✅ Store tokens in environment variables
• ✅ Use .env files (add to .gitignore)
• ✅ Regenerate tokens if exposed
• ✅ Use different tokens for different applications
• ❌ Never commit tokens to Git
• ❌ Never log tokens in application logs
• ❌ Never share tokens in forums/Discord

If your token is compromised:

1. Go to https://versedb.com/user/api-tokens
2. Delete the compromised token immediately
3. Generate a new token
4. Update your application with the new token

Respect API Versioning

The API is versioned (/api/v1). Always use the full versioned path:

✅ Good: https://versedb.com/api/v1/series/123
❌ Bad: https://versedb.com/api/series/123

This ensures your application continues working when API v2 is released.

Handle Pagination Correctly

List endpoints return paginated results:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 500,
    "last_page": 25
  },
  "links": {
    "first": "/api/v1/series?page=1",
    "next": "/api/v1/series?page=2",
    "prev": null,
    "last": "/api/v1/series?page=25"
  }
}

Iterate through pages:

async function fetchAllPages(baseUrl) {
  let allData = [];
  let nextUrl = baseUrl;
  
  while (nextUrl) {
    const response = await fetch(nextUrl);
    const json = await response.json();
    
    allData = allData.concat(json.data);
    nextUrl = json.links.next ? `https://versedb.com${json.links.next}` : null;
    
    // Respect rate limits between pages
    await sleep(200);
  }
  
  return allData;
}

Test with Public Endpoints First

Before implementing authentication, test your integration with public endpoints:

// Test connectivity
const testConnection = async () => {
  const response = await fetch('https://versedb.com/api/v1/publishers');
  if (response.ok) {
    console.log('API connection successful');
    console.log('Rate limit:', response.headers.get('X-RateLimit-Limit'));
  }
};

Summary

✅ DO:

• Cache public data (publishers, series, characters)
• Monitor rate limit headers
• Implement exponential backoff for 429 errors
• Use nested routes for related data
• Protect your API tokens
• Use versioned API paths (/v1)
• Test with public endpoints first

❌ DON'T:

• Hammer the API with rapid requests
• Ignore 429 responses
• Share or expose tokens
• Skip pagination for large datasets
• Cache personal data too aggressively
• Use search endpoints unnecessarily

Next: Learn about common errors in "Troubleshooting Common API Errors"