Api
API Datasource Integration Guide
This guide explains how to build an API that’s compatible with our datasource system. Follow these specifications to ensure your API works seamlessly with our platform.
API Requirements
API Endpoint
Your API endpoint must be publicly accessible with a valid domain or IP address:
✅ Valid Examples:
https://api.yoursite.com/items
https://yoursite.com/api/products
http://123.456.789.123:8080/api/data
https://subdomain.example.org/endpoint
❌ Invalid Examples:
http://localhost:3000/api
(localhost not accessible)http://127.0.0.1/api
(local IP not accessible)http://192.168.1.100/api
(private network not accessible)
Note: Your API must be accessible from external servers. Local development URLs cannot be reached by our system.
HTTP Method and Caching
Your API must support GET requests with these characteristics:
- Accept all parameters via query string
- Handle cache-busting parameters (we add
_nonce
automatically) - Return consistent results for identical requests
Response Format
Your API must return JSON responses in this exact format:
Field Requirements
Required Fields
Every item must include these fields:
Field | Type | Validation | Example |
---|---|---|---|
id | string | number | Must be unique, string or number | "123" or 456 |
title | string | Must be non-empty string | "Product Name" |
date_modified | string | Exact ISO 8601 UTC with milliseconds: YYYY-MM-DDTHH:mm:ss.SSSZ | "2024-03-20T15:30:45.000Z" |
Critical Date Format Requirements
The date_modified
field is strictly validated:
- ✅ Correct:
"2024-03-20T15:30:45.000Z"
- ❌ Wrong:
"2024-03-20T15:30:45Z"
(missing milliseconds) - ❌ Wrong:
"2024-03-20 15:30:45"
(wrong format) - ❌ Wrong:
"2024-03-20T15:30:45+00:00"
(wrong timezone format)
Optional Fields
These fields have special system recognition, but you can include any additional fields you need:
Field | Type | Description |
---|---|---|
description | string | Detailed description of the item |
price | number | Current price |
regular_price | number | Regular price before any discounts |
sale_price | number | Sale price if applicable |
stock_status | string | Stock status: instock , outofstock , onbackorder , or any custom value |
currency | string | Currency code: USD , EUR , IRR , ریال , تومان , or any custom code |
variations | array | Product variations with pricing and inventory |
...any_field | any | You can add any custom fields you need |
Variations Field Details
Each variation can include any fields you need. Common examples:
Field | Type | Description |
---|---|---|
id | string/number | Unique variation identifier |
title | string | Variation display name |
price | number | Variation price |
regular_price | number | Variation regular price |
sale_price | number | Variation sale price |
stock_status | string | Variation stock status |
stock | number | Available quantity |
...any_field | any | Any custom variation attributes |
Example 1 - E-commerce Product:
Example 2 - Q&A Knowledge Base:
Key Points:
- Fields in the table above get special recognition for search and filtering
- You can include unlimited custom fields for any data type (products, articles, Q&A, etc.)
- All data you send will be stored and made searchable
- Custom fields can be strings, numbers, objects, arrays, or any valid JSON type
Query Parameters
Your API must support all these parameters:
Pagination Parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
take | number | Yes | Number of items to return | ?take=30 |
skip | number | Yes | Number of items to skip | ?skip=60 |
Ordering Parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
order | string | Yes | Sort direction: ASC or DESC | ?order=ASC |
order_by | string | Yes | Fields to sort by (comma-separated) | ?order_by=date_modified,id |
Filtering Parameters
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
modified_after | string | Yes | ISO date - returns items modified after this date (excludes exact match) | ?modified_after=2024-03-20T15:30:45.000Z |
Cache Busting
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
_nonce | string | Auto | Automatically added by our system | ?_nonce=1679328645123 |
Authentication Methods
No Authentication
Leave authentication type as “none”. Your API will receive requests without authentication headers.
API Key Authentication
Configure your datasource with:
- API Key: Your actual key value
- Header Name: Custom header name (e.g.,
X-API-Key
,Authorization
)
Example request your API will receive:
Bearer Token Authentication
Standard OAuth 2.0 Bearer token format.
Example request your API will receive:
Validation Requirements
Your API will be tested for these capabilities:
1. Basic Structure
- Response has
total_count
(number) anditems
(array) - Items array is not empty
- Each item has required fields with correct types
2. Pagination Accuracy
Requirement: skip=0 returns first item, skip=1 returns second item exactly.
3. Ordering Functionality
Requirement: Both ASC/DESC work correctly, multi-field sorting supported.
4. Date Filtering Precision
Requirement: modified_after
must return only items with date_modified > filter_date
(greater than, not equal).
Implementation Examples
PHP Laravel
Node.js Express
Python FastAPI
Complete working example: For a full implementation with proper date validation, error handling, and multiple endpoints, check out our GitHub example repository.
Common Issues & Solutions
Date Format Errors
Problem: Date validation fails
Solution: Use exactly YYYY-MM-DDTHH:mm:ss.SSSZ
format with UTC timezone
Pagination Issues
Problem: Inconsistent results between pages
Solution: Ensure stable sorting with unique secondary field (like id
)
Authentication Failures
Problem: Invalid auth headers Solution: Verify header names match datasource configuration exactly
Testing Your API
Before integration, test these scenarios:
- Basic functionality:
GET /api?take=5
- Pagination:
GET /api?take=5&skip=5
- Ordering:
GET /api?order=DESC&order_by=date_modified
- Date filtering:
GET /api?modified_after=2024-01-01T00:00:00.000Z
- Combined parameters: All parameters together
Use tools like Postman or curl to verify your API meets all requirements before connecting to our system.