Skip to main content

API Integration Guide

Learn how to integrate Devcogent APIs into your applications with detailed examples and best practices.

Authentication​

Before making API calls, you need to authenticate using your API key:

const headers = {
  'Authorization': `Bearer ${process.env.DEVCOGENT_API_KEY}`,
  'Content-Type': 'application/json'
};

REST API Endpoints​

Base URL​

All API requests should be made to:

https://api.devcogent.com/v1

Common Endpoints​

Get User Information​

GET /users/{user_id}

Example Request:

const response = await fetch('https://api.devcogent.com/v1/users/123', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

const user = await response.json();

Create Resource​

POST /resources

Example Request:

const response = await fetch('https://api.devcogent.com/v1/resources', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'My Resource',
    type: 'document',
    data: { key: 'value' }
  })
});

const resource = await response.json();

SDK Integration​

JavaScript/Node.js​

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

const api = new DevcogentAPI({
  apiKey: process.env.DEVCOGENT_API_KEY,
  baseURL: 'https://api.devcogent.com/v1'
});

// Get user
const user = await api.users.get('123');

// Create resource
const resource = await api.resources.create({
  name: 'My Resource',
  type: 'document'
});

// Update resource
const updated = await api.resources.update('resource-id', {
  name: 'Updated Resource'
});

// Delete resource
await api.resources.delete('resource-id');

Python​

from devcogent import DevcogentAPI

api = DevcogentAPI(
    api_key=os.environ['DEVCOGENT_API_KEY'],
    base_url='https://api.devcogent.com/v1'
)

# Get user
user = api.users.get('123')

# Create resource
resource = api.resources.create({
    'name': 'My Resource',
    'type': 'document'
})

Response Format​

All API responses follow a consistent format:

{
  "success": true,
  "data": {
    "id": "123",
    "name": "Resource Name",
    "created_at": "2024-01-01T00:00:00Z"
  },
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 100
  }
}

Error Handling​

Error Response Format​

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "name",
      "reason": "Required field missing"
    }
  }
}

Handling Errors in Code​

try {
  const response = await api.resources.create(data);
  console.log('Success:', response.data);
} catch (error) {
  if (error.status === 400) {
    console.error('Validation error:', error.data.error.details);
  } else if (error.status === 401) {
    console.error('Authentication failed');
  } else if (error.status === 429) {
    console.error('Rate limit exceeded');
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Rate Limiting​

Devcogent APIs implement rate limiting to ensure fair usage:

  • Standard Plan: 100 requests per minute
  • Pro Plan: 1000 requests per minute
  • Enterprise: Custom limits

Handling Rate Limits​

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 retryAfter = error.headers['retry-after'] || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
}

// Usage
const result = await makeRequestWithRetry(() => 
  api.resources.create(data)
);

Pagination​

For endpoints that return multiple items:

// Get paginated results
const response = await api.resources.list({
  page: 1,
  limit: 50,
  sort: 'created_at',
  order: 'desc'
});

console.log('Items:', response.data);
console.log('Total:', response.meta.total);
console.log('Has more:', response.meta.page * response.meta.limit < response.meta.total);

Webhooks​

Set up webhooks to receive real-time updates:

Webhook Configuration​

// Register webhook endpoint
const webhook = await api.webhooks.create({
  url: 'https://your-app.com/webhooks/devcogent',
  events: ['resource.created', 'resource.updated', 'resource.deleted'],
  secret: 'your-webhook-secret'
});

Handling Webhook Events​

app.post('/webhooks/devcogent', (req, res) => {
  const signature = req.headers['x-devcogent-signature'];
  const payload = req.body;
  
  // Verify webhook signature
  if (!verifyWebhookSignature(payload, signature, webhookSecret)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process event
  switch (payload.event) {
    case 'resource.created':
      handleResourceCreated(payload.data);
      break;
    case 'resource.updated':
      handleResourceUpdated(payload.data);
      break;
    default:
      console.log('Unknown event:', payload.event);
  }
  
  res.status(200).send('OK');
});

Best Practices​

  1. Always use HTTPS for API requests
  2. Store API keys securely - never commit them to version control
  3. Implement proper error handling for all API calls
  4. Use appropriate timeouts for network requests
  5. Implement retry logic for transient failures
  6. Cache responses when appropriate to reduce API calls
  7. Use webhooks instead of polling for real-time updates

Next Steps​