Passa al contenuto principale

API Reference

Emblema fornisce un ecosistema completo di API per interagire con la piattaforma AI. Questa sezione copre tutte le interfacce disponibili per integrare i tuoi servizi con Emblema.

Panoramica delle API​

La piattaforma Emblema offre tre tipi principali di API:

🔗 REST API​

API RESTful complete per tutte le operazioni CRUD su entità, gestione file, chat AI e servizi di sistema.

  • Base URL: https://your-domain.com/api/v1
  • Autenticazione: JWT Token tramite Keycloak
  • Formato: JSON
  • Rate Limiting: Configurabile per ambiente

📊 GraphQL API​

API GraphQL unificata per query complesse e operazioni relazionali sui dati.

  • Endpoint: https://your-domain.com/v1/graphql (Hasura)
  • Autenticazione: JWT Token
  • Schema: Tipizzato e auto-documentato
  • Subscriptions: Real-time per aggiornamenti dati

🔄 Real-time API​

Sistema di notifiche real-time e monitoraggio stato servizi.

  • Protocollo: Server-Sent Events (SSE)
  • WebSocket: Per notifiche Novu
  • Health Check: Monitoraggio servizi in tempo reale

Guida Rapida​

Autenticazione​

Tutte le API richiedono autenticazione tramite JWT token:

# Ottenere il token tramite login Keycloak
curl -X POST https://keycloak.your-domain.com/auth/realms/emblema/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&client_id=emblema&username=user&password=pass"

# Utilizzare il token nelle chiamate API
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://your-domain.com/api/v1/document

Esempio Base - Lista Documenti​

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept-Language: it" \
  https://your-domain.com/api/v1/document?page=1&search=query

Risposta:

{
  "data": [
    {
      "id": "uuid",
      "name": "Document Name",
      "createdAt": "2024-01-15T10:00:00Z",
      "status": "active"
    }
  ],
  "total": 100
}

Sezioni della Documentazione​

Caratteristiche Principali​

Gestione Completa delle Entità​

  • CRUD Operations: Create, Read, Update, Delete per tutte le entità
  • Ricerca Avanzata: Full-text search con filtri e ordinamento
  • Paginazione: Gestione efficiente di grandi dataset
  • Permissions: Sistema granulare di permessi per ogni risorsa

AI e Machine Learning​

  • Chat API: Conversazioni AI con supporto multimodale
  • Document Processing: Elaborazione automatica con chunking intelligente
  • Knowledge Base: Semantic search e RAG (Retrieval Augmented Generation)
  • MCP Protocol: Model Context Protocol per estensioni AI

File Management​

  • Upload Chunked: Upload affidabile di file di grandi dimensioni
  • Processing Pipeline: Elaborazione automatica (PDF, Audio, Video)
  • Storage Distribuito: Integrazione MinIO per scalabilità
  • Metadata Extraction: Estrazione automatica di metadati

Real-time & Monitoring​

  • Task Processing: Monitoraggio asincrono di task lunghi
  • Health Checks: Controllo stato servizi in tempo reale
  • Notifications: Sistema di notifiche push tramite Novu
  • Service Status: Dashboard di monitoraggio servizi

Esempi di Integrazione​

Quick Start con JavaScript​

// Configurazione client
const apiClient = {
  baseURL: "https://your-domain.com/api/v1",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
    "Accept-Language": "it",
  },
};

// Crea un documento
const document = await fetch(`${apiClient.baseURL}/document`, {
  method: "POST",
  headers: apiClient.headers,
  body: JSON.stringify({
    name: "Nuovo Documento",
    description: "Descrizione del documento",
  }),
});

// Avvia una chat
const chatResponse = await fetch(`${apiClient.baseURL}/chat`, {
  method: "POST",
  headers: apiClient.headers,
  body: JSON.stringify({
    messages: [{ role: "user", content: "Ciao!" }],
    selectedChatModel: "gpt-4",
    id: crypto.randomUUID(),
  }),
});

Python SDK Example​

import requests
from typing import Dict, Any

class EmblemaClient:
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json',
            'Accept-Language': 'it'
        }

    def create_document(self, name: str, description: str = None) -> Dict[str, Any]:
        response = requests.post(
            f'{self.base_url}/document',
            headers=self.headers,
            json={'name': name, 'description': description}
        )
        return response.json()

    def chat(self, messages: list, model: str = 'gpt-4') -> requests.Response:
        return requests.post(
            f'{self.base_url}/chat',
            headers=self.headers,
            json={
                'messages': messages,
                'selectedChatModel': model,
                'id': str(uuid.uuid4())
            },
            stream=True
        )

# Utilizzo
client = EmblemaClient('https://your-domain.com/api/v1', 'your-token')
doc = client.create_document('Test Document')

Risorse Aggiuntive​

Supporto​

Per supporto tecnico sulle API:

Questa pagina ti è stata utile?