Entities API

REST API για τη διαχείριση προσαρμοσμένων οντοτήτων και των εγγραφών τους.

Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com/api - δείτε Επισκόπηση API.

Επισκόπηση

Το Entities API σας επιτρέπει προγραμματιστικά να:

• Δημιουργείτε και διαχειρίζεστε ορισμούς οντοτήτων (σχήματα)
• Προσθέτετε, ενημερώνετε και διαγράφετε εγγραφές οντοτήτων (δεδομένα)
• Εκτελείτε ερωτήματα και αναζητήσεις σε εγγραφές
• Διαχειρίζεστε πεδία και σχέσεις οντοτήτων

Έλεγχος ταυτότητας

Όλα τα endpoints απαιτούν έλεγχο ταυτότητας μέσω bearer token:

Authorization: Bearer YOUR_API_KEY

Και το πλαίσιο χώρου εργασίας μέσω κεφαλίδας:

X-Workspace-Id: YOUR_WORKSPACE_ID

Ορισμοί οντοτήτων

Λίστα όλων των οντοτήτων

Λήψη όλων των ορισμών οντοτήτων στον τρέχοντα χώρο εργασίας.

GET /entities

Απόκριση:

[
  {
    "id": "uuid",
    "organizationId": "uuid",
    "workspaceId": "uuid",
    "name": "products",
    "displayName": "Products",
    "description": "Product catalog",
    "collectionName": "entity_products",
    "primaryKey": "_id",
    "displayField": "name",
    "settings": {
      "allowDuplicates": false,
      "enableAudit": true,
      "enableVersioning": false,
      "softDelete": true
    },
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]

Λήψη οντότητας βάσει ID

Ανάκτηση συγκεκριμένου ορισμού οντότητας.

GET /entities/:entityId

Απόκριση:

{
  "id": "uuid",
  "name": "products",
  "displayName": "Products",
  ...
}

Δημιουργία οντότητας

Δημιουργία νέου ορισμού οντότητας με πεδία.

POST /entities

Σώμα αιτήματος:

{
  "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
    },
    {
      "name": "description",
      "displayName": "Description",
      "fieldType": "markdown",
      "displayOrder": 3
    },
    {
      "name": "active",
      "displayName": "Active",
      "fieldType": "boolean",
      "validation": {
        "default": true
      },
      "displayOrder": 4
    }
  ],
  "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

Απόκριση:

{
  "id": "uuid",
  "name": "products",
  ...
}

Ενημέρωση οντότητας

Ενημέρωση ορισμού οντότητας (όνομα, περιγραφή, ρυθμίσεις).

PUT /entities/:entityId

Σώμα αιτήματος:

{
  "displayName": "Updated Products",
  "description": "Updated description",
  "displayField": "sku",
  "settings": {
    "enableAudit": false
  }
}

Διαγραφή οντότητας

Διαγραφή μιας οντότητας και όλων των εγγραφών της.

DELETE /entities/:entityId

Απόκριση: 204 No Content

Προειδοποίηση: Αυτό διαγράφει οριστικά το σχήμα της οντότητας και όλες τις εγγραφές!

Πεδία οντοτήτων

Λίστα πεδίων

Λήψη όλων των πεδίων μιας οντότητας.

GET /entities/:entityId/fields

Απόκριση:

[
  {
    "id": "uuid",
    "entityDefinitionId": "uuid",
    "name": "sku",
    "displayName": "SKU",
    "description": "Product SKU",
    "fieldType": "string",
    "validation": {
      "required": true,
      "unique": true,
      "minLength": 5,
      "maxLength": 20
    },
    "indexed": true,
    "indexType": "btree",
    "displayOrder": 0,
    "hidden": false,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]

Προσθήκη πεδίου

Προσθήκη νέου πεδίου σε μια οντότητα.

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

Παράμετροι query:

• filter - Αντικείμενο φίλτρου JSON (κωδικοποιημένο σε URL)
• sort - Αντικείμενο ταξινόμησης JSON (κωδικοποιημένο σε URL)
• limit - Μέγιστες εγγραφές που επιστρέφονται (προεπιλογή: 50)
• offset - Πλήθος εγγραφών που παραλείπονται (προεπιλογή: 0)

Παραδείγματα:

# All active products
GET /entities/ENTITY_ID/records?filter={"active":true}

# Products sorted by price descending
GET /entities/ENTITY_ID/records?sort={"price":-1}

# Paginated results
GET /entities/ENTITY_ID/records?limit=20&offset=40

Απόκριση:

{
  "data": [
    {
      "_id": "665f1c0a9b2e4d0012ab34cd",
      "sku": "PROD-001",
      "name": "Widget",
      "price": 29.99,
      "description": "A great widget",
      "active": true,
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 150
}

Λήψη εγγραφής βάσει ID

Ανάκτηση συγκεκριμένης εγγραφής.

GET /entities/:entityId/records/:recordId

Απόκριση:

{
  "_id": "665f1c0a9b2e4d0012ab34cd",
  "sku": "PROD-001",
  "name": "Widget",
  ...
}

Δημιουργία εγγραφής

Προσθήκη νέας εγγραφής σε μια οντότητα.

POST /entities/:entityId/records

Σώμα αιτήματος:

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

Επικύρωση:

• Τα απαιτούμενα πεδία πρέπει να υπάρχουν
• Τα μοναδικά πεδία πρέπει να είναι μοναδικά
• Οι τιμές πρέπει να ταιριάζουν με τους τύπους των πεδίων
• Οι περιορισμοί min/max επιβάλλονται

Απόκριση:

{
  "_id": "665f1c0a9b2e4d0012ab34cd",
  "sku": "PROD-001",
  ...
}

Ενημέρωση εγγραφής

Ενημέρωση υπάρχουσας εγγραφής.

PUT /entities/:entityId/records/:recordId

Σώμα αιτήματος:

{
  "price": 34.99,
  "description": "An even better widget"
}

Υποστηρίζονται μερικές ενημερώσεις - συμπεριλάβετε μόνο τα πεδία που θέλετε να αλλάξετε.

Διαγραφή εγγραφής

Αφαίρεση εγγραφής από μια οντότητα.

DELETE /entities/:entityId/records/:recordId

Απόκριση: 204 No Content

Αν είναι ενεργοποιημένη η ήπια διαγραφή (soft delete), η εγγραφή επισημαίνεται ως διαγραμμένη. Διαφορετικά, αφαιρείται οριστικά.

Μαζική δημιουργία εγγραφών (σώμα-πίνακας)

Δεν υπάρχει ξεχωριστό endpoint μαζικών λειτουργιών: το POST /entities/:entityId/records δέχεται είτε ένα μεμονωμένο αντικείμενο εγγραφής είτε έναν σκέτο πίνακα JSON με αντικείμενα εγγραφών (χωρίς αντικείμενο-περιτύλιγμα). Η μορφή πίνακα δημιουργεί έως 1000 εγγραφές σε ένα αίτημα.

POST /entities/:entityId/records

Παράμετροι query:

• triggerAlerts - Ορίστε το σε true για να ενεργοποιηθούν ειδοποιήσεις σχέσεων (επιστροφή σε απόθεμα και παρόμοιες) για εγγραφές που μεταβαίνουν σε αυτή την εισαγωγή (προεπιλογή: false)

Σώμα αιτήματος:

Ένας πίνακας JSON (μέγιστο 1000 στοιχεία· κενός πίνακας ή περισσότερα από 1000 επιστρέφει 400). Κάθε στοιχείο χρησιμοποιεί το ίδιο περίβλημα data με τη μορφή μεμονωμένου αντικειμένου.

Το περίβλημα κάθε στοιχείου επικυρώνεται ξεχωριστά: ένα στοιχείο χωρίς αντικείμενο data αναφέρεται στο failed με τον δείκτη του στον πίνακα - δεν γίνεται ποτέ σιωπηλά αποδεκτό - και τα υπόλοιπα έγκυρα στοιχεία εξακολουθούν να εισάγονται. Η επικύρωση βάσει ορισμών πεδίων (απαιτούμενα πεδία, τύποι, min/max) εφαρμόζεται σε ολόκληρη την παρτίδα, ακριβώς όπως στις μεμονωμένες δημιουργίες.

[
  {
    "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	IDs των εγγραφών που δημιουργήθηκαν, με τη σειρά εισαγωγής
failed	Αποτυχίες περιβλήματος ανά στοιχείο: index (θέση στον πίνακα του αιτήματος), reason

Αναζήτηση

Αναζήτηση εγγραφών

Αναζήτηση πλήρους κειμένου σε καθορισμένα πεδία.

GET /entities/:entityId/search

Παράμετροι query:

• q - Ερώτημα αναζήτησης (απαιτείται)
• fields - Ονόματα πεδίων προς αναζήτηση, χωρισμένα με κόμμα (προαιρετικό)
• limit - Μέγιστα αποτελέσματα (προεπιλογή: 10)

Παραδείγματα:

# Search across all indexed fields
GET /entities/ENTITY_ID/search?q=widget

# Search specific fields
GET /entities/ENTITY_ID/search?q=PROD-001&fields=sku,name

# Limit results
GET /entities/ENTITY_ID/search?q=widget&limit=5

Απόκριση:

[
  {
    "_id": "id",
    "sku": "PROD-001",
    "name": "Widget",
    ...
  }
]

Σύνθετα ερωτήματα

Συγκεντρωτικά (aggregation)

Εκτέλεση συγκεντρωτικών υπολογισμών σε εγγραφές οντοτήτων.

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": [
    {
      "category": "Electronics",
      "avgPrice": 45.99,
      "totalValue": 2299.50,
      "productCount": 50
    },
    {
      "category": "Clothing",
      "avgPrice": 29.99,
      "totalValue": 1499.50,
      "productCount": 50
    }
  ]
}

Πολύπλοκα ερωτήματα

Εκτέλεση πολύπλοκων ερωτημάτων με σύνταξη τύπου MongoDB.

POST /entities/query

Σώμα αιτήματος:

{
  "entity": "products",
  "pipeline": [
    {
      "$match": {
        "price": { "$gte": 20, "$lte": 50 },
        "active": true
      }
    },
    {
      "$group": {
        "_id": "$category",
        "count": { "$sum": 1 },
        "avgPrice": { "$avg": "$price" }
      }
    },
    {
      "$sort": { "avgPrice": -1 }
    }
  ]
}

Τελεστές φίλτρων

Στα φίλτρα μπορείτε να χρησιμοποιήσετε τελεστές ερωτημάτων MongoDB:

Σύγκριση

• $eq - Ίσο με
• $ne - Διάφορο από
• $gt - Μεγαλύτερο από
• $gte - Μεγαλύτερο ή ίσο
• $lt - Μικρότερο από
• $lte - Μικρότερο ή ίσο
• $in - Τιμή μέσα σε πίνακα
• $nin - Τιμή εκτός πίνακα

Λογικοί

• $and - Λογικό ΚΑΙ
• $or - Λογικό Ή
• $not - Λογικό ΟΧΙ
• $nor - Λογικό NOR

Στοιχείου

• $exists - Το πεδίο υπάρχει
• $type - Έλεγχος τύπου πεδίου

Συμβολοσειράς

• $regex - Αντιστοίχιση κανονικής έκφρασης

Παραδείγματα:

// Price between 10 and 100
{
  "price": { "$gte": 10, "$lte": 100 }
}

// Active products in specific categories
{
  "active": true,
  "category": { "$in": ["Electronics", "Computers"] }
}

// Complex condition
{
  "$or": [
    { "price": { "$lte": 20 } },
    { "onSale": true }
  ],
  "active": true
}

Αποκρίσεις σφαλμάτων

400 Bad Request

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "price",
      "message": "price must be greater than or equal to 0"
    }
  ]
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Entity not found"
}

409 Conflict

{
  "statusCode": 409,
  "message": "Duplicate value for unique field 'sku'"
}

Όρια ρυθμού

Το Entities API δεν έχει σήμερα σταθερά όρια ρυθμού ανά endpoint - δείτε Επισκόπηση API: Όρια ρυθμού για τη συμπεριφορά σε επίπεδο πλατφόρμας και τον χειρισμό των αποκρίσεων 429.

Καλές πρακτικές

Απόδοση

1. Χρησιμοποιείτε ευρετήρια - Βάλτε σε ευρετήριο τα πεδία στα οποία φιλτράρετε/αναζητάτε συχνά
2. Σελιδοποιείτε τα αποτελέσματα - Μην ανακτάτε όλες τις εγγραφές μονομιάς
3. Περιορίζετε την επιλογή πεδίων - Ανακτάτε μόνο τα πεδία που χρειάζεστε
4. Κάνετε cache τις αποκρίσεις - Αποθηκεύετε προσωρινά τα δεδομένα με συχνή πρόσβαση
5. Ομαδοποιείτε τις λειτουργίες - Χρησιμοποιείτε τα μαζικά endpoints όπου είναι δυνατόν

Ποιότητα δεδομένων

1. Επικυρώνετε πριν την εισαγωγή - Ελέγχετε τα δεδομένα στην πλευρά του πελάτη
2. Χειρίζεστε τα σφάλματα - Υλοποιήστε σωστό χειρισμό σφαλμάτων
3. Χρησιμοποιείτε συναλλαγές - Για λειτουργίες πολλαπλών εγγραφών
4. Καθαρίζετε τακτικά - Αρχειοθετείτε ή διαγράφετε παλιές εγγραφές

Ασφάλεια

1. Μην εκθέτετε ποτέ κλειδιά API - Κρατήστε τα στην πλευρά του διακομιστή
2. Επικυρώνετε την είσοδο χρήστη - Καθαρίζετε τα δεδομένα πριν τα στείλετε στο API
3. Χρησιμοποιείτε μόνο HTTPS - Ποτέ HTTP
4. Εναλλάσσετε τα κλειδιά τακτικά - Ενημερώνετε τα κλειδιά API περιοδικά
5. Υλοποιήστε όρια ρυθμού - Και από τη δική σας πλευρά

Παραδείγματα κώδικα

JavaScript/Node.js

const axios = require('axios');

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

// Create entity
const entity = await api.post('/entities', {
  name: 'products',
  displayName: 'Products',
  fields: [/* ... */]
});

// Create record
const record = await api.post(`/entities/${entity.data.id}/records`, {
  sku: 'PROD-001',
  name: 'Widget',
  price: 29.99
});

// Search records
const results = await api.get(`/entities/${entity.data.id}/search`, {
  params: { q: 'widget' }
});

Python

import requests
import os

api_key = os.getenv('HIPPO_API_KEY')
workspace_id = os.getenv('WORKSPACE_ID')

headers = {
    'Authorization': f'Bearer {api_key}',
    'X-Workspace-Id': workspace_id
}

# Create entity
response = requests.post(
    'https://api-eu1.joryio.com/api/entities',
    json={
        'name': 'products',
        'displayName': 'Products',
        'fields': [...]
    },
    headers=headers
)
entity = response.json()

# Create record
response = requests.post(
    f'https://api-eu1.joryio.com/api/entities/{entity["id"]}/records',
    json={
        'sku': 'PROD-001',
        'name': 'Widget',
        'price': 29.99
    },
    headers=headers
)

Σχέσεις και επιλογές προϊόντων

Σχέσεις

GET /entities/relationships
POST /entities/relationships

Μια σχέση δηλώνει ότι ένας τύπος οντότητας δείχνει σε άλλον - μια παραγγελία σε έναν πελάτη, μια συνδρομή σε ένα πλάνο. Η δήλωση επιτρέπει σε φίλτρα και εξατομίκευση να διασχίσουν τον σύνδεσμο αντί να διπλασιάζουν τα δεδομένα και στις δύο πλευρές. Το type είναι one_to_one, many_to_one ή many_to_many, και το foreignKey είναι το πεδίο της οντότητας προέλευσης που κρατά το id.

{ "from": "subscription", "to": "plan", "type": "many_to_one", "foreignKey": "planId" }

Επιλογές προϊόντων

GET /entities/product-selections
POST /entities/product-selections
GET /entities/product-selections/:selectionId/match-count

Το match-count επιστρέφει τον πραγματικό αριθμό προϊόντων που ταιριάζουν στην επιλογή αυτή τη στιγμή ({ matchCount, cap }). Η προεπισκόπηση επιστρέφει το πολύ cap γραμμές - το όριο της επιλογής, έως 50 - οπότε δεν μπορεί να πει το μέγεθος της αντιστοιχίας.

Ένα αποθηκευμένο ερώτημα πάνω σε μια οντότητα που επιλύεται σε λίστα εγγραφών τη στιγμή της αποστολής - "τα 5 κορυφαία σε έσοδα σε αυτή την κατηγορία". Τα μπλοκ προτάσεων και οι κόμβοι ταξιδιού αναφέρονται στην επιλογή, ώστε το περιεχόμενο να παραμένει επίκαιρο χωρίς επανασυγγραφή.

{
  "name": "Bestsellers - outerwear",
  "entityType": "product",
  "filters": { "operator": "AND", "conditions": [
    { "field": "category", "operator": "equals", "value": "outerwear" }
  ] },
  "sort": { "field": "unitsSold", "direction": "desc" },
  "limit": 5
}

Σχετική τεκμηρίωση

• Επισκόπηση προσαρμοσμένων οντοτήτων