Entities API

REST API لإدارة الكيانات المخصصة وسجلاتها.

كل النقاط هنا نسبية إلى عنوان الأساس https://api-eu1.joryio.com. راجع نظرة عامة على API.

نظرة عامة

تتيح Entities API برمجياً:

إنشاء تعريفات الكيانات، أي المخططات، وإدارتها.
إضافة سجلات الكيانات وتحديثها وحذفها.
الاستعلام عن السجلات والبحث فيها.
إدارة الحقول والعلاقات.

المصادقة

تتطلب كل النقاط Bearer token وسياق مساحة العمل:

Authorization: Bearer YOUR_API_KEY
X-Workspace-Id: YOUR_WORKSPACE_ID

تعريفات الكيانات

عرض كل الكيانات

GET /entities

يعيد تعريفات الكيانات في مساحة العمل، بكل من id وname وdisplayName وdescription وcollectionName وprimaryKey وdisplayField وإعدادات التكرارات والتدقيق والإصدارات والحذف الناعم والطوابع الزمنية.

الحصول على كيان

GET /entities/:entityId

يعيد تعريف الكيان المحدد.

إنشاء كيان

POST /entities

يقبل name وdisplayName وdescription وdisplayField ومصفوفة fields وsettings.

{
  "name": "products",
  "displayName": "Products",
  "description": "Product catalog with pricing",
  "displayField": "name",
  "fields": [
    {
      "name": "sku",
      "displayName": "SKU",
      "fieldType": "string",
      "validation": { "required": true, "unique": true, "minLength": 5, "maxLength": 20 },
      "indexed": true,
      "displayOrder": 0
    },
    {
      "name": "name",
      "displayName": "Product Name",
      "fieldType": "string",
      "validation": { "required": true, "maxLength": 255 },
      "displayOrder": 1
    },
    {
      "name": "price",
      "displayName": "Price",
      "fieldType": "currency",
      "validation": { "required": true, "min": 0 },
      "displayOrder": 2
    }
  ],
  "settings": { "allowDuplicates": false, "enableAudit": true, "enableVersioning": false, "softDelete": true }
}

أنواع الحقول:

string وemail وphone وurl.
number وinteger وcurrency وpercentage.
boolean وdate وdatetime.
markdown وhtml وjson.
image_url وfile_url.

تحديث كيان

PUT /entities/:entityId

حدّث اسم العرض أو الوصف أو حقل العرض أو الإعدادات.

حذف كيان

DELETE /entities/:entityId

يعيد 204 No Content.

خطر

يحذف ذلك تعريف الكيان وكل سجلاته نهائياً.

حقول الكيان

عرض الحقول

GET /entities/:entityId/fields

يعيد كل حقل، شاملاً الاسم واسم العرض والوصف ونوع الحقل والتحقق والفهرسة ونوع الفهرس وترتيب العرض وحالة الإخفاء والطوابع الزمنية.

إضافة حقل

POST /entities/:entityId/fields

{
  "name": "category",
  "displayName": "Category",
  "fieldType": "string",
  "validation": { "required": false },
  "indexed": true,
  "displayOrder": 5
}

حذف حقل

DELETE /entities/:entityId/fields/:fieldId

يعيد 204 No Content.

تحذير

يحذف ذلك تعريف الحقل. لا تحذف بيانات السجلات الحالية، لكنها تصبح غير قابلة للوصول.

سجلات الكيان

عرض السجلات

GET /entities/:entityId/records

المعامل	الوصف
`filter`	كائن فلتر JSON مشفر في URL.
`sort`	كائن ترتيب JSON مشفر في URL.
`limit`	أقصى سجلات، الافتراضي 50.
`offset`	السجلات المتجاوزة، الافتراضي 0.

GET /entities/ENTITY_ID/records?filter={"active":true}
GET /entities/ENTITY_ID/records?sort={"price":-1}
GET /entities/ENTITY_ID/records?limit=20&offset=40

تعيد الاستجابة data للسجلات وtotal للعدد الكلي.

الحصول على سجل

GET /entities/:entityId/records/:recordId

إنشاء سجل

POST /entities/:entityId/records

{
  "sku": "PROD-001",
  "name": "Widget",
  "price": 29.99,
  "description": "A great widget",
  "active": true
}

تتحقق العملية من الحقول المطلوبة والتفرد وأنواع الحقول وقيود الحد الأدنى والأقصى.

تحديث سجل

PUT /entities/:entityId/records/:recordId

يدعم التحديث الجزئي؛ أرسل الحقول التي تريد تغييرها فقط.

حذف سجل

DELETE /entities/:entityId/records/:recordId

يعيد 204 No Content. عند تفعيل الحذف الناعم يُعلّم السجل محذوفاً، وإلا يُزال نهائياً.

إنشاء سجلات جماعياً، نص مصفوفة

لا توجد نقطة جماعية منفصلة: يقبل POST /entities/:entityId/records كائن سجل أو مصفوفة JSON مجردة، وينشئ حتى 1000 سجل في الطلب.

معامل الاستعلام	الوصف
`triggerAlerts`	اضبطه `true` لتشغيل تنبيهات العلاقات، مثل إعادة التوفر، للسجلات التي تنتقل في الاستيراد. الافتراضي `false`.

تستخدم كل عناصر المصفوفة غلاف data نفسه المستخدم في الإنشاء المفرد. تعيد المصفوفة الفارغة أو التي تتجاوز 1000 رمز 400. يُبلغ عن عنصر بلا data في failed بفهرسه ولا يُقبل بصمت، وتستمر العناصر الصالحة. ينطبق تحقق تعريف الحقول على الدفعة كما في الإنشاء المفرد.

[
  { "data": { "sku": "PROD-001", "name": "Widget A", "price": 29.99 } },
  { "data": { "sku": "PROD-002", "name": "Widget B", "price": 39.99 } }
]

{
  "processed": 2,
  "inserted": 2,
  "insertedIds": ["id-1", "id-2"],
  "failed": []
}

الحقل	الوصف
`processed`	عدد عناصر مصفوفة الطلب.
`inserted`	السجلات المنشأة فعلياً.
`insertedIds`	معرّفات السجلات المنشأة بترتيب الإدراج.
`failed`	أخطاء غلاف كل عنصر: `index` و`reason`.

البحث

البحث في السجلات

GET /entities/:entityId/search

المعامل	الوصف
`q`	استعلام البحث، مطلوب.
`fields`	أسماء الحقول المفصولة بفاصلة، اختياري.
`limit`	أقصى نتائج، الافتراضي 10.

ابحث في كل الحقول المفهرسة أو حدد حقولاً، مثل ?q=PROD-001&fields=sku,name. يعيد مصفوفة سجلات.

الاستعلامات المتقدمة

التجميع

POST /entities/:entityId/aggregate

{
  "groupBy": "category",
  "aggregations": [
    { "field": "price", "operation": "avg", "as": "avgPrice" },
    { "field": "price", "operation": "sum", "as": "totalValue" },
    { "operation": "count", "as": "productCount" }
  ]
}

العمليات المدعومة: count وsum وavg وmin وmax. تعيد الاستجابة results مجمعة بحسب الحقل.

الاستعلامات المعقدة

POST /entities/query

نفذ استعلامات بأسلوب MongoDB مع entity وpipeline، مثل $match لنطاق سعر وحالة active، ثم $group حسب الفئة و$sort للسعر المتوسط.

عوامل تشغيل الفلاتر

تدعم الفلاتر عوامل استعلام MongoDB:

المقارنة: $eq و$ne و$gt و$gte و$lt و$lte و$in و$nin.
المنطق: $and و$or و$not و$nor.
العناصر: $exists و$type.
النص: $regex.

{ "price": { "$gte": 10, "$lte": 100 } }
{ "active": true, "category": { "$in": ["Electronics", "Computers"] } }
{ "$or": [{ "price": { "$lte": 20 } }, { "onSale": true }], "active": true }

استجابات الأخطاء

الحالة	المثال
`400`	فشل تحقق، مثل سعر أصغر من 0.
`401`	غير مصادق.
`404`	الكيان غير موجود.
`409`	قيمة مكررة لحقل فريد مثل `sku`.

حدود المعدل

لا تملك Entities API حدود معدل ثابتة لكل نقطة نهاية حالياً. راجع نظرة API العامة: حدود المعدل وطريقة التعامل مع 429.

أفضل الممارسات

الأداء

فهرس الحقول التي تصفي أو تبحث بها كثيراً.
رقّم النتائج ولا تجلب كل السجلات دفعة واحدة.
اجلب الحقول التي تحتاجها فقط.
خزّن البيانات كثيرة الوصول مؤقتاً.
استخدم العمليات الجماعية عند الإمكان.

جودة البيانات

تحقق من البيانات قبل الإدراج.
عالج الأخطاء بطريقة صحيحة.
استخدم المعاملات للعمليات متعددة السجلات.
نظف البيانات وأرشف أو احذف السجلات القديمة بانتظام.

الأمان

لا تكشف مفاتيح API؛ احتفظ بها في الخادم.
تحقق من مدخلات المستخدم ونظفها قبل الإرسال.
استخدم HTTPS فقط.
بدّل المفاتيح دورياً.
طبق حدود معدل في جانبك أيضاً.

أمثلة كود

JavaScript / Node.js

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://api-eu1.joryio.com',
  headers: {
    'Authorization': `Bearer ${process.env.HIPPO_API_KEY}`,
    'X-Workspace-Id': process.env.WORKSPACE_ID
  }
});

const entity = await api.post('/entities', { name: 'products', displayName: 'Products', fields: [/* ... */] });
const record = await api.post(`/entities/${entity.data.id}/records`, { sku: 'PROD-001', name: 'Widget', price: 29.99 });
const results = await api.get(`/entities/${entity.data.id}/search`, { params: { q: 'widget' } });

Python

import requests
import os

headers = {
    'Authorization': f'Bearer {os.getenv("HIPPO_API_KEY")}',
    'X-Workspace-Id': os.getenv('WORKSPACE_ID')
}
response = requests.post('https://api-eu1.joryio.com/entities', json={
    'name': 'products', 'displayName': 'Products', 'fields': [...]
}, headers=headers)
entity = response.json()

توثيق ذو صلة

نظرة عامة على الكيانات المخصصة

نظرة عامة​

المصادقة​

تعريفات الكيانات​

عرض كل الكيانات​

الحصول على كيان​

إنشاء كيان​

تحديث كيان​

حذف كيان​

حقول الكيان​

عرض الحقول​

إضافة حقل​

حذف حقل​

سجلات الكيان​

عرض السجلات​

الحصول على سجل​

إنشاء سجل​

تحديث سجل​

حذف سجل​

إنشاء سجلات جماعياً، نص مصفوفة​

البحث​

البحث في السجلات​

الاستعلامات المتقدمة​

التجميع​

الاستعلامات المعقدة​

عوامل تشغيل الفلاتر​

استجابات الأخطاء​

حدود المعدل​

أفضل الممارسات​

الأداء​

جودة البيانات​

الأمان​

أمثلة كود​

JavaScript / Node.js​

Python​

توثيق ذو صلة​