Best Practices for Using the VerseDB API

Cache Your Requests

If you're requesting the same data frequently, cache the results locally. This reduces unnecessary API calls and helps you stay within your hourly rate limit.

Batch Requests Carefully

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/{id}/items/{item_id}  # Remove single item

For user lists:

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

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

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 = parseInt(response.headers.get('Retry-After') || '60');
      console.log(`Rate limited. Waiting ${retryAfter}s before retry ${attempt + 1}`);
      await sleep(retryAfter * 1000);
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

Always Authenticate

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

Leverage Search Endpoints Efficiently

Search endpoints have stricter rate limits (60/hour free, 120/hour PRO). Use them wisely:

Use Nested Routes for Related Data (PRO)

PRO users can access nested routes to efficiently fetch related data:

GET /api/series/{id}/issues           # Get issues for a series
GET /api/series/{id}/creators         # Get creators for a series
GET /api/issues/{id}/variants         # Get variants for an issue
GET /api/teams/{id}/characters        # Get team members

Protect Your Token

If your token is compromised:

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

Handle Pagination Correctly

List endpoints return paginated results:

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

Iterate through pages:

async function fetchAllPages(baseUrl, token) {
  let allData = [];
  let nextUrl = baseUrl;
  
  while (nextUrl) {
    const response = await fetch(nextUrl, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    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 Connectivity First

Before implementing your integration, test your authentication:

const testConnection = async (token) => {
  const response = await fetch('https://versedb.com/api/user', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  
  if (response.ok) {
    console.log('API connection successful');
    console.log('Rate limit:', response.headers.get('X-RateLimit-Limit'));
  } else {
    console.error('Authentication failed:', response.status);
  }
};