​

API Datasource Structure

This documentation explains how to structure your API endpoint to be compatible with our datasource integration system.

​

Base Requirements

Your API endpoint must:

• Accept POST requests
• Return JSON responses
• Support pagination, ordering, and date-based filtering
• Return items in a consistent format

​

API Response Format

Your API must return responses in the following format:

{
  "total_count": 100, // Total number of items available
  "items": [
    // Array of items
    {
      "id": "123", // String or number (required)
      "title": "Product Name", // String (required)
      "date_modified": "2024-03-20T15:30:45.000Z" // ISO 8601 UTC date string (required)
      // ... other optional fields
    }
  ]
}

​

Required Fields

Each item in the response must have these required fields:

​

Optional Fields

You can include additional fields in your items:

​

Query Parameters

Your API must support the following query parameters:

​

Authentication

The API supports three authentication methods:

​

No Authentication

No additional headers required. Your API endpoint will be called without any authentication headers.

​

API Key Authentication

Add your API key in a custom header:

X-API-Key: your-api-key-here

You can customize the header name during datasource configuration (e.g., Authorization, X-Custom-Key, etc.).

​

Bearer Token Authentication

Use the standard Bearer token format in the Authorization header:

Authorization: Bearer your-token-here

​

Example Requests

​

Basic Request with API Key

POST /endpoint?take=10&skip=0
Host: your-api.com
X-API-Key: your-api-key-here
Content-Type: application/json

​

Paginated Request with Bearer Token

POST /endpoint?take=10&skip=20&order=DESC&order_by=date_modified,id
Host: your-api.com
Authorization: Bearer your-token-here
Content-Type: application/json

​

Filtered Request without Authentication

POST /endpoint?take=10&modified_after=2024-03-20T15:30:45.000Z
Host: your-api.com
Content-Type: application/json

​

Validation Rules

Your API must follow these validation rules:

1. Date format must be exact ISO 8601 with UTC timezone and milliseconds (e.g., "2024-03-20T15:30:45.000Z")
2. Pagination must be exact (e.g., skip=1 must return the second item)
3. Ordering must work correctly for both ascending and descending orders
4. Date filtering must be precise and exclude the exact match date
5. Empty results must return an empty items array, not null or undefined

​

Error Handling

Your API should return appropriate HTTP status codes and error messages:

• 200: Successful response
• 400: Bad request (invalid parameters)
• 401: Unauthorized (invalid authentication)
• 403: Forbidden (insufficient permissions)
• 500: Server error

​

Best Practices

1. Always include the total count for proper pagination handling
2. Use consistent date formats across all endpoints
3. Implement proper caching headers
4. Rate limit your API to prevent abuse
5. Document any additional fields or features specific to your implementation

​

Testing Your API

Before integrating, ensure your API:

1. Returns consistent results for the same query parameters
2. Handles pagination correctly
3. Processes date filters accurately
4. Sorts results properly
5. Authenticates requests correctly
6. Returns proper error messages for invalid requests