اتصال منبع دادهٔ API

{
  "total_count": 100,
  "items": [
    {
      "id": "123",
      "title": "Product Name",
      "date_modified": "2026-10-20T15:30:45.000Z",
      "description": "Detailed product description...",
      "url": "https://example.com/products/123",
      "price": 29.99,
      "regular_price": 39.99,
      "sale_price": 29.99,
      "stock_status": "instock",
      "currency": "USD",
      "variations": [
        { "id": "456", "title": "Size L", "price": 32.99 }
      ]
    }
  ]
}

{
  "id": "123",
  "title": "Wireless Headphones",
  "date_modified": "2024-03-20T15:30:45.000Z",
  "description": "High-quality wireless headphones...",
  "price": 99.99,
  "regular_price": 129.99,
  "sale_price": 99.99,
  "stock_status": "instock",
  "currency": "USD",
  "category": "electronics",
  "brand": "TechBrand",
  "sku": "WH-123",
  "weight": 0.3,
  "variations": [
    {
      "id": "123-black-large",
      "title": "Wireless Headphones - Black Large",
      "price": 99.99,
      "regular_price": 129.99,
      "sale_price": 99.99,
      "stock_status": "instock",
      "stock": 25,
      "color": "black",
      "size": "large",
      "sku": "WH-123-BL",
      "weight": 0.35
    },
    {
      "id": "123-white-medium",
      "title": "Wireless Headphones - White Medium",
      "price": 104.99,
      "regular_price": 129.99,
      "sale_price": 104.99,
      "stock_status": "outofstock",
      "stock": 0,
      "color": "white",
      "size": "medium",
      "sku": "WH-123-WM",
      "expected_restock": "2024-04-15"
    },
    {
      "id": "123-red-small",
      "title": "Wireless Headphones - Red Small",
      "price": 94.99,
      "regular_price": 129.99,
      "sale_price": 94.99,
      "stock_status": "onbackorder",
      "stock": 5,
      "color": "red",
      "size": "small",
      "sku": "WH-123-RS",
      "pre_order": true
    }
  ]
}

{
  "id": 1,
  "title": "What is Python?",
  "date_modified": "2024-03-15T12:00:00.000Z",
  "question": "What is Python?",
  "answer": "Python is a high-level, interpreted programming language known for its simplicity and readability."
}

GET /api/items?take=10&skip=0&_nonce=1792497600000 HTTP/1.1
Host: api.example.com
X-API-Key: your-api-key-here

GET /api/items?take=10&skip=0&_nonce=1792497600000 HTTP/1.1
Host: api.example.com
Authorization: Bearer your-token-here

GET /api/items?take=2&order=ASC&order_by=date_modified,id
GET /api/items?take=1&skip=0&order=ASC&order_by=date_modified,id
GET /api/items?take=1&skip=1&order=ASC&order_by=date_modified,id

GET /api/items?take=2&order=ASC&order_by=date_modified,id
GET /api/items?take=2&order=DESC&order_by=date_modified,id
GET /api/items?take=1&order=ASC&order_by=date_modified,id

<?php

namespace App\Http\Controllers;

use App\Models\Item;
use Carbon\CarbonImmutable;
use Illuminate\Http\Request;
use Illuminate\Validation\ValidationException;

class DatasourceController extends Controller
{
    public function index(Request $request)
    {
        $params = $request->validate([
            'take' => ['sometimes', 'integer', 'min:1', 'max:100'],
            'skip' => ['sometimes', 'integer', 'min:0'],
            'order' => ['sometimes', 'in:ASC,DESC'],
            'order_by' => ['sometimes', 'string'],
            'modified_after' => [
                'sometimes', 'date',
                'regex:/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/',
            ],
        ]);
        $columns = ['date_modified' => 'updated_at', 'id' => 'id'];
        $fields = array_map('trim', explode(',', $params['order_by'] ?? 'date_modified,id'));
        foreach ($fields as $field) {
            if (!isset($columns[$field])) {
                throw ValidationException::withMessages(['order_by' => 'Unsupported field']);
            }
        }
        if (!in_array('id', $fields, true)) {
            $fields[] = 'id';
        }

        $query = Item::query();
        if (isset($params['modified_after'])) {
            $since = CarbonImmutable::parse($params['modified_after'])->utc();
            $query->where('updated_at', '>', $since->format('Y-m-d H:i:s.v'));
        }
        $total = (clone $query)->count();
        foreach (array_unique($fields) as $field) {
            $query->orderBy($columns[$field], $params['order'] ?? 'ASC');
        }
        $items = $query->offset((int) ($params['skip'] ?? 0))
            ->limit((int) ($params['take'] ?? 30))->get();

        return response()->json([
            'total_count' => $total,
            'items' => $items->map(fn ($item) => [
                'id' => (string) $item->id,
                'title' => $item->title,
                'date_modified' => $item->updated_at->copy()->utc()
                    ->format('Y-m-d\TH:i:s.v\Z'),
                'description' => $item->description,
                'price' => $item->price === null ? null : (float) $item->price,
            ])->values(),
        ]);
    }
}

use App\Http\Controllers\DatasourceController;
use Illuminate\Support\Facades\Route;

Route::get('/items', [DatasourceController::class, 'index']);

import express from "express";
import Item from "./models/item.js";

const router = express.Router();
const columns = { date_modified: "updated_at", id: "_id" };

router.get("/api/items", async (req, res, next) => {
  const {
    take = "30", skip = "0", order = "ASC",
    order_by = "date_modified,id", modified_after
  } = req.query;
  const integers = [take, skip].every((value) =>
    typeof value === "string" && /^\d+$/.test(value)
  );
  const limit = Number(take);
  const offset = Number(skip);
  if (!integers || !Number.isSafeInteger(limit) || limit < 1 || limit > 100
      || !Number.isSafeInteger(offset) || offset < 0) {
    return res.status(400).json({ error: "Invalid take or skip" });
  }
  if (!["ASC", "DESC"].includes(order) || typeof order_by !== "string") {
    return res.status(400).json({ error: "Invalid ordering" });
  }
  const fields = [...new Set(order_by.split(",").map((field) => field.trim()))];
  if (fields.some((field) => !Object.hasOwn(columns, field))) {
    return res.status(400).json({ error: "Unsupported order_by field" });
  }
  if (!fields.includes("id")) fields.push("id");

  const filter = {};
  if (modified_after !== undefined) {
    const since = typeof modified_after === "string" ? new Date(modified_after) : null;
    if (!since || Number.isNaN(since.getTime())) {
      return res.status(400).json({ error: "Invalid modified_after timestamp" });
    }
    const canonical = since.toISOString();
    if (![canonical, canonical.replace(".000Z", "Z")].includes(modified_after)) {
      return res.status(400).json({ error: "Use UTC ISO 8601 with seconds or milliseconds" });
    }
    filter.updated_at = { $gt: since };
  }
  const sort = Object.fromEntries(fields.map((field) => [
    columns[field], order === "DESC" ? -1 : 1
  ]));
  try {
    const [total_count, items] = await Promise.all([
      Item.countDocuments(filter),
      Item.find(filter).sort(sort).skip(offset).limit(limit).lean()
    ]);
    return res.json({
      total_count,
      items: items.map((item) => ({
        id: String(item._id),
        title: item.title,
        date_modified: item.updated_at.toISOString(),
        description: item.description,
        price: item.price
      }))
    });
  } catch (error) {
    next(error);
  }
});

export default router;

import datasourceRouter from "./datasource-router.js";

app.use(datasourceRouter);

import json
import os
from datetime import datetime, timezone
from pathlib import Path
from secrets import compare_digest
from typing import Literal

from fastapi import Depends, FastAPI, HTTPException, Query, Security
from fastapi.security import APIKeyHeader, HTTPAuthorizationCredentials, HTTPBearer

app = FastAPI()
api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
bearer_auth = HTTPBearer(auto_error=False)


def verify_api_key(api_key: str | None = Security(api_key_header)):
    expected = os.environ.get("DATASOURCE_API_KEY")
    if not expected or not api_key or not compare_digest(api_key, expected):
        raise HTTPException(status_code=401, detail="Invalid API key")


def verify_bearer_token(
    credentials: HTTPAuthorizationCredentials | None = Security(bearer_auth),
):
    expected = os.environ.get("DATASOURCE_BEARER_TOKEN")
    if not expected or not credentials or not compare_digest(credentials.credentials, expected):
        raise HTTPException(status_code=401, detail="Invalid bearer token")


def parse_timestamp(value: str) -> datetime:
    try:
        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
        canonical = parsed.astimezone(timezone.utc).isoformat(timespec="milliseconds")
        canonical = canonical.replace("+00:00", "Z")
        if parsed.tzinfo is None or value not in {canonical, canonical.replace(".000Z", "Z")}:
            raise ValueError
        return parsed
    except (TypeError, ValueError):
        raise HTTPException(status_code=422, detail="Use UTC ISO 8601 with seconds or milliseconds")


def load_json_file() -> list[dict]:
    path = Path(__file__).with_name("items.json")
    items = json.loads(path.read_text(encoding="utf-8"))
    return [{**item, "id": str(item["id"])} for item in items]


@app.get("/api/items")
def get_items(
    take: int = Query(default=30, ge=1, le=100),
    skip: int = Query(default=0, ge=0),
    order_by: str = "date_modified,id",
    order: Literal["ASC", "DESC"] = "ASC",
    modified_after: str | None = None,
    # API key authentication: uncomment the next line.
    # api_key: None = Depends(verify_api_key),
    # Bearer authentication: uncomment the next line instead.
    # bearer: None = Depends(verify_bearer_token),
):
    fields = list(dict.fromkeys(field.strip() for field in order_by.split(",")))
    if any(field not in {"date_modified", "id"} for field in fields):
        raise HTTPException(status_code=422, detail="Unsupported order_by field")
    if "id" not in fields:
        fields.append("id")
    items = load_json_file()
    if modified_after is not None:
        since = parse_timestamp(modified_after)
        items = [item for item in items if parse_timestamp(item["date_modified"]) > since]
    for field in reversed(fields):
        items.sort(
            key=lambda item: parse_timestamp(item[field]) if field == "date_modified" else item[field],
            reverse=order == "DESC",
        )
    total_count = len(items)
    return {"total_count": total_count, "items": items[skip:skip + take]}

[
  {
    "id": "1",
    "title": "Wireless Headphones",
    "date_modified": "2026-10-20T09:30:00.000Z",
    "description": "Wireless headphones with a microphone.",
    "price": 99.99,
    "currency": "USD"
  },
  {
    "id": "2",
    "title": "USB-C Cable",
    "date_modified": "2026-10-20T09:30:00.000Z",
    "description": "A one-meter USB-C charging cable.",
    "price": 9.99,
    "currency": "USD"
  },
  {
    "id": "3",
    "title": "What is Python?",
    "date_modified": "2026-10-21T12:00:00.000Z",
    "question": "What is Python?",
    "answer": "Python is a high-level programming language."
  }
]

pip install "fastapi[standard]"
fastapi dev main.py

curl --get 'https://api.example.com/items' --data-urlencode 'take=5'
curl --get 'https://api.example.com/items' --data-urlencode 'take=5' \
  --data-urlencode 'skip=5' --data-urlencode 'order_by=date_modified,id'

curl --get 'https://api.example.com/items' --data-urlencode 'order=DESC' \
  --data-urlencode 'order_by=date_modified,id'
curl --get 'https://api.example.com/items' \
  --data-urlencode 'modified_after=2026-10-20T09:30:00.000Z'
curl --get 'https://api.example.com/items' \
  --data-urlencode 'modified_after=2026-10-20T09:30:00Z'

curl --get 'https://api.example.com/items' \
  --header 'X-API-Key: your-api-key-here' \
  --data-urlencode 'take=31' --data-urlencode 'skip=0' \
  --data-urlencode 'order=ASC' --data-urlencode 'order_by=date_modified,id' \
  --data-urlencode 'modified_after=2026-10-20T09:30:00.000Z' \
  --data-urlencode '_nonce=1792497600000'