Best Practices

​

Authentication & Security

​

API Key Management

• Environment Variables: Store API keys in environment variables, never in code
• Key Rotation: Regularly rotate API keys for enhanced security
• Separate Keys: Use different keys for development, staging, and production
• Monitoring: Monitor API key usage and set up alerts for unusual activity

# Good: Environment variable
export ELECTRONHUB_API_KEY="your_api_key_here"

# Bad: Hardcoded in source
const apiKey = "ek-1234567890abcdef"; // Never do this!

​

Request Security

• HTTPS Only: Always use HTTPS endpoints
• Input Validation: Validate and sanitize all user inputs
• Rate Limiting: Implement client-side rate limiting
• Error Handling: Don’t expose sensitive information in error messages

​

Performance Optimization

​

Request Optimization

• Batch Requests: Group multiple operations when possible
• Streaming: Use streaming for real-time applications
• Caching: Cache responses for repeated queries
• Connection Pooling: Reuse HTTP connections

// Good: Batch embedding requests
const embeddings = await fetch('/v1/embeddings', {
  method: 'POST',
  body: JSON.stringify({
    input: ['text1', 'text2', 'text3'], // Multiple inputs
    model: 'text-embedding-3-small'
  })
});

// Less efficient: Individual requests
for (const text of texts) {
  const embedding = await fetch('/v1/embeddings', {
    method: 'POST',
    body: JSON.stringify({
      input: text,
      model: 'text-embedding-3-small'
    })
  });
}

​

Model Selection

• Start Small: Begin with cost-effective models for prototyping
• Upgrade Selectively: Use premium models only when necessary
• Context Awareness: Choose models based on context length requirements
• Task Matching: Match model capabilities to your specific use case

​

Cost Management

​

Token Optimization

• Monitor Usage: Track token consumption across all endpoints
• Prompt Engineering: Write efficient prompts that minimize tokens
• Context Management: Remove unnecessary context from conversations
• Model Scaling: Use appropriate models for different complexity levels

​

Smart Caching

// Implement response caching
const cache = new Map();

async function getChatCompletion(messages, model) {
  const cacheKey = JSON.stringify({ messages, model });
  
  if (cache.has(cacheKey)) {
    return cache.get(cacheKey);
  }
  
  const response = await electronhub.chat.completions.create({
    messages,
    model
  });
  
  cache.set(cacheKey, response);
  return response;
}

​

Error Handling

​

Robust Error Management

• Retry Logic: Implement exponential backoff for transient errors
• Graceful Degradation: Provide fallbacks for API failures
• Error Classification: Handle different error types appropriately
• User Experience: Show meaningful error messages to users

async function makeAPICall(requestFn, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429) {
        // Rate limit - exponential backoff
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      
      if (error.status >= 500 && attempt < maxRetries) {
        // Server error - retry
        continue;
      }
      
      // Other errors or max retries reached
      throw error;
    }
  }
}

​

Status Code Handling

• 200-299: Success - process response
• 400-499: Client errors - check request format
• 429: Rate limited - implement backoff
• 500-599: Server errors - retry with caution

​

Prompt Engineering

​

Chat Completions

• Clear Instructions: Be specific about what you want
• System Messages: Use system messages to set context and behavior
• Few-shot Examples: Provide examples for complex tasks
• Format Specification: Clearly specify desired output format

// Good: Clear, specific prompt
{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant that summarizes articles in exactly 3 bullet points."
    },
    {
      "role": "user", 
      "content": "Summarize this article: [article text]"
    }
  ]
}

// Less effective: Vague prompt
{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "Tell me about this article: [article text]"
    }
  ]
}

​

Image Generation

• Descriptive Prompts: Include details about style, composition, and quality
• Aspect Ratios: Specify appropriate sizes for your use case
• Style Consistency: Use consistent terminology across related images
• Quality Settings: Choose appropriate quality levels for your needs

​

Monitoring & Observability

​

Usage Tracking

• Token Metrics: Monitor token usage per endpoint
• Error Rates: Track success/failure rates
• Response Times: Measure API latency
• Cost Analysis: Monitor spending across different models

​

Logging Best Practices

// Structured logging example
const logger = {
  logAPICall: (endpoint, model, tokens, responseTime, status) => {
    console.log(JSON.stringify({
      timestamp: new Date().toISOString(),
      endpoint,
      model,
      tokens,
      responseTime,
      status,
      environment: process.env.NODE_ENV
    }));
  }
};

// Usage
const startTime = Date.now();
try {
  const response = await electronhub.chat.completions.create({
    model: 'gpt-3.5-turbo',
    messages: messages
  });
  
  logger.logAPICall(
    'chat/completions',
    'gpt-3.5-turbo',
    response.usage.total_tokens,
    Date.now() - startTime,
    'success'
  );
} catch (error) {
  logger.logAPICall(
    'chat/completions',
    'gpt-3.5-turbo',
    0,
    Date.now() - startTime,
    'error'
  );
}

​

Development Workflow

​

Testing Strategy

• Unit Tests: Test individual API interactions
• Integration Tests: Test complete workflows
• Load Testing: Verify performance under load
• Error Scenarios: Test failure conditions

​

Environment Management

• Development: Use cheaper models and lower limits
• Staging: Mirror production setup for testing
• Production: Implement full monitoring and alerting

​

Version Control

• API Versioning: Always specify API versions
• Model Versioning: Pin specific model versions for consistency
• Configuration Management: Version control all API configurations

​

Compliance & Ethics

​

Content Guidelines

• Content Policy: Ensure all content complies with usage policies
• Moderation: Use the Moderations API for user-generated content
• Privacy: Respect user privacy and data protection regulations
• Transparency: Be transparent about AI usage with users

​

Responsible AI

• Bias Awareness: Be aware of potential model biases
• Human Oversight: Maintain human review for critical decisions
• Fallback Plans: Have non-AI alternatives for critical functions
• User Control: Give users control over AI interactions