Technical FAQ

Technical questions and troubleshooting for developers using Devcogent.

API and Integration

Q: What is the base URL for the Devcogent API?

A: The base URL for all API requests is:

https://api.devcogent.com/v1

For development/testing, you can use:

https://dev-api.devcogent.com/v1

Q: How do I authenticate API requests?

A: Use Bearer token authentication in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.devcogent.com/v1/endpoint

Q: What response format does the API use?

A: All API responses are in JSON format:

{
  "success": true,
  "data": {
    "id": "123",
    "name": "Example"
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "version": "1.0"
  }
}

Q: How do I handle pagination?

A: Use the page and limit parameters:

const response = await fetch('https://api.devcogent.com/v1/data?page=1&limit=50');
const data = await response.json();

console.log(`Page ${data.meta.page} of ${data.meta.total_pages}`);
console.log(`${data.meta.total} total items`);

Error Handling

Q: What HTTP status codes does the API return?

A: Common status codes:

200: Success
201: Created
400: Bad Request (invalid parameters)
401: Unauthorized (invalid API key)
403: Forbidden (insufficient permissions)
404: Not Found
429: Too Many Requests (rate limited)
500: Internal Server Error
503: Service Unavailable (maintenance)

Q: How should I handle rate limiting?

A: Implement exponential backoff when you receive a 429 response:

async function makeRequestWithRetry(requestFn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await requestFn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const backoff = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, backoff));
        continue;
      }
      throw error;
    }
  }
}

Q: How do I debug API responses?

A: Enable debug mode in the SDK:

const client = new Devcogent({
  apiKey: 'your-api-key',
  debug: true, // Enables detailed logging
  logging: {
    level: 'debug',
    requests: true,
    responses: true
  }
});

SDK Usage

Q: How do I install the JavaScript SDK?

A: Install via npm or yarn:

npm install @devcogent/sdk
# or
yarn add @devcogent/sdk

Q: How do I initialize the SDK?

A: Basic initialization:

import { Devcogent } from '@devcogent/sdk';

const client = new Devcogent({
  apiKey: process.env.DEVCOGENT_API_KEY,
  environment: 'production' // or 'development'
});

Q: Can I use the SDK in the browser?

A: Yes, but be careful with API keys:

// For client-side apps, use a public key or proxy through your backend
const client = new Devcogent({
  publicKey: 'your-public-key', // Not your private API key
  environment: 'production'
});

Q: How do I handle async operations?

A: All SDK methods return Promises:

// Using async/await
try {
  const result = await client.getData();
  console.log(result);
} catch (error) {
  console.error('Error:', error.message);
}

// Using .then()/.catch()
client.getData()
  .then(result => console.log(result))
  .catch(error => console.error('Error:', error.message));

Performance and Optimization

Q: How can I improve API response times?

A: Several optimization strategies:

Use compression:

const client = new Devcogent({
  apiKey: 'your-api-key',
  compression: true // Enable gzip compression
});

Implement caching:

const cache = new Map();

async function getCachedData(key) {
  if (cache.has(key)) {
    return cache.get(key);
  }
  
  const data = await client.getData(key);
  cache.set(key, data);
  
  // Expire cache after 5 minutes
  setTimeout(() => cache.delete(key), 5 * 60 * 1000);
  
  return data;
}

Batch requests:

// Instead of multiple individual requests
const results = await Promise.all([
  client.getData('id1'),
  client.getData('id2'),
  client.getData('id3')
]);

// Use batch API if available
const results = await client.getBatchData(['id1', 'id2', 'id3']);

Q: Should I pool connections?

A: Yes, connection pooling improves performance:

const client = new Devcogent({
  apiKey: 'your-api-key',
  pool: {
    maxConnections: 50,
    keepAlive: true,
    timeout: 30000
  }
});

Q: How do I handle large datasets?

A: Use streaming or pagination:

// Streaming approach
const stream = client.getDataStream();
stream.on('data', chunk => processChunk(chunk));
stream.on('end', () => console.log('Stream complete'));

// Pagination approach
async function processAllData() {
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await client.getData({ page, limit: 100 });
    await processData(response.data);
    
    hasMore = response.data.length === 100;
    page++;
  }
}

Security

Q: How should I store API keys securely?

A: Best practices for API key storage:

Use environment variables:

# .env file (never commit to version control)
DEVCOGENT_API_KEY=your_secret_key_here

Use secret management services:

// AWS Secrets Manager example
const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();

const secret = await secretsManager.getSecretValue({
  SecretId: 'devcogent-api-key'
}).promise();

const apiKey = JSON.parse(secret.SecretString).apiKey;

Never expose keys in client-side code:

// ❌ Don't do this
const apiKey = 'sk_live_abc123'; // Visible to users

// ✅ Do this instead
// Proxy sensitive operations through your backend
app.post('/api/proxy', async (req, res) => {
  const result = await client.processData(req.body);
  res.json(result);
});

Q: How do I validate webhook signatures?

A: Verify webhook authenticity:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// Express.js example
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-devcogent-signature'];
  
  if (!verifyWebhookSignature(req.body, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  handleWebhook(req.body);
  res.status(200).send('OK');
});

Environment and Deployment

Q: How do I set up different environments?

A: Use environment-specific configurations:

const config = {
  development: {
    apiKey: process.env.DEVCOGENT_DEV_KEY,
    baseURL: 'https://dev-api.devcogent.com',
    debug: true
  },
  production: {
    apiKey: process.env.DEVCOGENT_PROD_KEY,
    baseURL: 'https://api.devcogent.com',
    debug: false
  }
};

const client = new Devcogent(config[process.env.NODE_ENV]);

Q: How do I handle timeouts in production?

A: Set appropriate timeouts and implement retry logic:

const client = new Devcogent({
  apiKey: 'your-api-key',
  timeout: 30000, // 30 seconds
  retries: 3,
  retryDelay: 1000 // 1 second between retries
});

// Custom timeout handling
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 25000);

try {
  const result = await client.getData({
    signal: controller.signal
  });
  clearTimeout(timeoutId);
  return result;
} catch (error) {
  clearTimeout(timeoutId);
  if (error.name === 'AbortError') {
    throw new Error('Request timed out');
  }
  throw error;
}

Q: How do I monitor API health in production?

A: Implement health checks and monitoring:

// Health check endpoint
app.get('/health', async (req, res) => {
  try {
    const start = Date.now();
    await client.ping(); // Test API connectivity
    const responseTime = Date.now() - start;
    
    res.json({
      status: 'healthy',
      devcogent: {
        connected: true,
        responseTime: `${responseTime}ms`
      }
    });
  } catch (error) {
    res.status(503).json({
      status: 'unhealthy',
      devcogent: {
        connected: false,
        error: error.message
      }
    });
  }
});

// Monitoring with custom metrics
client.on('request', (data) => {
  // Log metrics to your monitoring system
  metrics.recordAPICall({
    endpoint: data.endpoint,
    method: data.method,
    duration: data.duration,
    status: data.status
  });
});

Troubleshooting

Q: Why am I getting "Module not found" errors?

A: Common solutions:

Check installation:

npm list @devcogent/sdk

Clear cache and reinstall:

rm -rf node_modules package-lock.json
npm install

Check import syntax:

// ✅ Correct
import { Devcogent } from '@devcogent/sdk';

// ❌ Incorrect
import Devcogent from '@devcogent/sdk';

Q: Why are my requests failing with CORS errors?

A: CORS issues occur in browser environments:

Use a backend proxy (recommended):

// Frontend
const response = await fetch('/api/devcogent-proxy', {
  method: 'POST',
  body: JSON.stringify(data)
});

// Backend (Express.js)
app.post('/api/devcogent-proxy', async (req, res) => {
  const result = await client.processData(req.body);
  res.json(result);
});

Configure CORS (if you control the domain):

// Add to your server
app.use(cors({
  origin: 'https://yourdomain.com',
  credentials: true
}));

Q: How do I debug network issues?

A: Enable network debugging:

// Node.js - enable debug logging
process.env.DEBUG = 'devcogent:*';

// Browser - check network tab in DevTools
// Enable verbose logging
const client = new Devcogent({
  apiKey: 'your-api-key',
  debug: true,
  logging: {
    level: 'trace' // Most verbose level
  }
});

Need more help?

API and Integration​

Error Handling​

SDK Usage​

Performance and Optimization​

Security​

Environment and Deployment​

Troubleshooting​