NIL Taxonomy Client

The NILTaxonomyClient provides typed access to the NIL Taxonomy API.

Basic Usage

import { NILTaxonomyClient } from '@nil-taxonomy/sdk';
 
const client = new NILTaxonomyClient({
  baseUrl: 'https://api.nil-taxonomy.org/api/nil',
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
});

Configuration Options

interface ClientConfig {
  baseUrl: string;      // API base URL
  apiKey: string;       // Your API key (required)
  timeout?: number;     // Request timeout in ms (default: 30000)
  retries?: number;     // Retry attempts (default: 3)
  retryDelay?: number;  // Delay between retries in ms (default: 1000)
}

Example with All Options

const client = new NILTaxonomyClient({
  baseUrl: process.env.NIL_TAXONOMY_API_URL!,
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
  timeout: 60000,       // 60 second timeout
  retries: 5,           // Retry up to 5 times
  retryDelay: 2000,     // Wait 2s between retries
});

API Methods

Get Versions

Fetch available taxonomy versions:

const versions = await client.getVersions();
// Returns: ['v1.0', 'v1.1', ...]

Get Dimensions

Fetch all taxonomy dimensions for a version:

const dimensions = await client.getDimensions('v1');
 
console.log(dimensions.subject_scope);
// {
//   name: 'Subject Scope',
//   description: 'What aspects of the athlete are covered',
//   values: ['name', 'image', 'likeness', ...]
// }

Get Base Licenses

Fetch all base license templates:

const licenses = await client.getBaseLicenses('v1');
 
licenses.forEach(license => {
  console.log(license.code, license.name);
});
// NIL-EDU Educational License
// NIL-COMM-STD Standard Commercial
// ...

Get Single Base License

Fetch a specific base license by code:

const eduLicense = await client.getBaseLicense('NIL-EDU', 'v1');
 
console.log(eduLicense);
// {
//   code: 'NIL-EDU',
//   name: 'Educational License',
//   config: { ... }
// }

Get Schema

Fetch the complete taxonomy schema:

const schema = await client.getSchema('v1');
 
// Full schema including dimensions, enums, and validation rules
console.log(schema.dimensions);
console.log(schema.base_licenses);

Error Handling

The client throws errors for failed requests. Always wrap in try/catch:

try {
  const licenses = await client.getBaseLicenses('v1');
  console.log('✓ Fetched licenses:', licenses.length);
} catch (error) {
  if (error.message.includes('Unauthorized')) {
    console.error('Invalid API key');
  } else if (error.message.includes('timeout')) {
    console.error('Request timed out');
  } else {
    console.error('Unexpected error:', error);
  }
}

Common Errors

Error	Cause	Solution
`Unauthorized`	Invalid API key	Check key in environment variables
`Rate limit exceeded`	Too many requests	Implement caching or upgrade tier
`Not Found`	Invalid version or code	Verify version/code exists
`Timeout`	Slow network	Increase timeout or check connection

Best Practices

1. Cache Taxonomy Data

Taxonomy data rarely changes. Cache it to reduce API calls:

let cachedLicenses: BaseLicense[] | null = null;
 
async function getBaseLicenses() {
  if (!cachedLicenses) {
    cachedLicenses = await client.getBaseLicenses('v1');
  }
  return cachedLicenses;
}

2. Use Environment Variables

Never hardcode API keys:

// ✅ Good
const client = new NILTaxonomyClient({
  baseUrl: process.env.NIL_TAXONOMY_API_URL!,
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
});
 
// ❌ Bad
const client = new NILTaxonomyClient({
  baseUrl: 'https://...',
  apiKey: 'nilk_hardcoded_key', // NEVER DO THIS
});

3. Handle Network Failures Gracefully

async function fetchWithFallback() {
  try {
    return await client.getBaseLicenses('v1');
  } catch (error) {
    console.warn('API fetch failed, using fallback data');
    return FALLBACK_LICENSES; // Local backup data
  }
}

4. Version Pinning

Always specify the taxonomy version explicitly:

// ✅ Good: Explicit version
const licenses = await client.getBaseLicenses('v1');
 
// ⚠️ Risky: Default version may change
const licenses = await client.getBaseLicenses();

Advanced Usage

Custom HTTP Client

If you need to customize the underlying HTTP client:

import { NILTaxonomyClient } from '@nil-taxonomy/sdk';
 
class CustomClient extends NILTaxonomyClient {
  async request(path: string, options: RequestInit) {
    // Add custom headers, logging, etc.
    console.log('API request:', path);
    return super.request(path, options);
  }
}

Batch Requests

Fetch multiple resources in parallel:

const [versions, dimensions, licenses] = await Promise.all([
  client.getVersions(),
  client.getDimensions('v1'),
  client.getBaseLicenses('v1'),
]);

Next Steps

Authentication License Builder