Entities API

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

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

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

Απόδοση

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

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

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

Ασφάλεια

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

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

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
  }
});

// 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/entities',
    json={
        'name': 'products',
        'displayName': 'Products',
        'fields': [...]
    },
    headers=headers
)
entity = response.json()

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

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

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

Επισκόπηση​

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

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

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

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

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

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

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

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

Λίστα πεδίων​

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

Διαγραφή πεδίου​

Εγγραφές οντοτήτων​

Λίστα εγγραφών​

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

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

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

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

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

Αναζήτηση​

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

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

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

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

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

Σύγκριση​

Λογικοί​

Στοιχείου​

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

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

400 Bad Request​

401 Unauthorized​

404 Not Found​

409 Conflict​

Όρια ρυθμού​

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

Απόδοση​

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

Ασφάλεια​

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

JavaScript/Node.js​

Python​

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

Επισκόπηση

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

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

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

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

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

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

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

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

Λίστα πεδίων

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

Διαγραφή πεδίου

Εγγραφές οντοτήτων

Λίστα εγγραφών

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

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

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

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

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

Αναζήτηση

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

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

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

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

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

Σύγκριση

Λογικοί

Στοιχείου

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

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

400 Bad Request

401 Unauthorized

404 Not Found

409 Conflict

Όρια ρυθμού

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

Απόδοση

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

Ασφάλεια

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

JavaScript/Node.js

Python

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