Guida Migrazione API

Guida completa per migrare dalle versioni precedenti alle nuove API di Emblema versione 0.0.1.

Migrazione da Pre-0.0.1 a 0.0.1

🔄 Cambiamenti Architetturali Principali

Rimozione Pattern SPP

Prima (SPP-based):

# Pattern obsoleto - NON PIÙ SUPPORTATO
GET /api/v1/spp-retrieval/search
POST /api/v1/spp-document-processor/process

Ora (Entity-based):

# Nuovo pattern gerarchico
GET /api/v1/KnowledgeBase/{kb-id}/Document/{doc-id}/Chunk
POST /api/v1/Document/{doc-id}/action/process

Sistema di Permessi

Prima: Permessi per ogni servizio SPP

Ora: Permessi gerarchici su entità radice

• Permessi verificati solo su root entity (KnowledgeBase)
• Permessi cascade automatico su entità figlie
• Ownership automatica per creatori

📋 Breaking Changes

1. Endpoint Structure Changes

❌ DEPRECATED - Rimuovere entro Marzo 2025:

# Endpoint obsoleti che saranno rimossi
POST /api/spp-retrieval/search
GET /api/spp-document/status
PUT /api/spp-chunks/update

✅ NUOVO Pattern:

# Pattern gerarchico con entity nesting
GET /api/v1/{Entity1}/{id1}/{Entity2}/{id2}
POST /api/v1/{Entity1}/{id1}/{Entity2}/{id2}/action/{actionName}

# Esempi concreti:
GET /api/v1/KnowledgeBase/kb-123/Document/doc-456/Chunk
POST /api/v1/Document/doc-123/action/rechunk
PUT /api/v1/Meeting/meet-789/Document/doc-456/action/updateMetadata

2. Authentication Changes

Prima:

// Service-specific tokens
const sppToken = await getServiceToken("spp-retrieval");
const docToken = await getServiceToken("spp-document");

Ora:

// Single JWT token per tutte le API
const token = await getAuthToken(); // JWT from Keycloak
headers: { 'Authorization': `Bearer ${token}` }

3. Response Format Standardization

Prima (Inconsistente):

// Formato variabile per servizio
{
  "status": "ok",
  "results": [...],
  "meta": {...}
}

Ora (Standardizzato):

{
  "success": true,
  "data": {
    "items": [...],
    "total": 42,
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalPages": 3
    }
  }
}

🛠️ Migration Steps

Step 1: Aggiornare Autenticazione

// PRIMA
class OldApiClient {
  async authenticate() {
    const sppToken = await this.getServiceToken("spp-retrieval");
    const docToken = await this.getServiceToken("spp-document");
    this.tokens = { spp: sppToken, doc: docToken };
  }
}

// DOPO
class NewApiClient {
  async authenticate() {
    this.token = await this.getKeycloakToken();
  }

  get headers() {
    return { Authorization: `Bearer ${this.token}` };
  }
}

Step 2: Migrare Endpoint Calls

// PRIMA - Service-specific endpoints
const searchResults = await fetch("/api/spp-retrieval/search", {
  method: "POST",
  headers: { Authorization: `Bearer ${tokens.spp}` },
  body: JSON.stringify({ query: "test", limit: 10 }),
});

// DOPO - Entity-based hierarchy
const searchResults = await fetch("/api/v1/KnowledgeBase/kb-123/search", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
  body: JSON.stringify({ query: "test", limit: 10 }),
});

Step 3: Aggiornare Response Handling

// PRIMA - Vari formati di response
const handleResponse = (response) => {
  if (response.status === "ok") {
    return response.results || response.data || response.items;
  }
  throw new Error(response.error || response.message);
};

// DOPO - Formato standardizzato
const handleResponse = (response) => {
  if (response.success) {
    return response.data;
  }
  throw new Error(response.error?.message || "Unknown error");
};

📋 Endpoint Mapping Table

Funzione	Prima (SPP)	Ora (Entity-based)
Search Documents	POST /api/spp-retrieval/search	POST /api/v1/KnowledgeBase/{id}/search
Process Document	POST /api/spp-document/process	POST /api/v1/Document/{id}/action/process
Get Chunks	GET /api/spp-chunks/document/{id}	GET /api/v1/Document/{id}/Chunk
Update Chunk	PUT /api/spp-chunks/{id}	PUT /api/v1/Document/{docId}/Chunk/{chunkId}
Rechunk Document	POST /api/spp-chunks/rechunk	POST /api/v1/Document/{id}/action/rechunk
Document Status	GET /api/spp-document/status/{id}	GET /api/v1/Document/{id}

🔍 New Features in 1.0.0

Entity Actions Pattern

# Azioni specifiche su entità
POST /api/v1/Document/{id}/action/rechunk
POST /api/v1/Meeting/{id}/action/generateSummary
POST /api/v1/KnowledgeBase/{id}/action/export
POST /api/v1/User/{id}/action/resetPassword

Bulk Operations

# Operazioni bulk su collections
POST /api/v1/KnowledgeBase/{id}/Document/bulk
PUT /api/v1/Document/bulk/action/reprocess
DELETE /api/v1/KnowledgeBase/{id}/Document/bulk

Advanced Search

# Search con filtri avanzati
POST /api/v1/KnowledgeBase/{id}/search
{
  "query": "intelligenza artificiale",
  "filters": {
    "documentType": ["pdf", "docx"],
    "dateRange": {
      "from": "2024-01-01",
      "to": "2024-12-31"
    },
    "tags": ["AI", "machine-learning"]
  },
  "options": {
    "includeChunks": true,
    "highlightMatches": true,
    "similarityThreshold": 0.7
  }
}

⚠️ Deprecation Timeline

Data	Milestone
Gennaio 2025	Release 1.0.0 - Dual support (old + new APIs)
Febbraio 2025	Deprecation warnings per old endpoints
Marzo 2025	REMOVAL - Old SPP endpoints definitivamente rimossi

🧪 Testing Migration

Migration Test Suite

describe("API Migration Tests", () => {
  test("Old endpoint returns deprecation warning", async () => {
    const response = await fetch("/api/spp-retrieval/search");
    expect(response.headers.get("X-Deprecation-Warning")).toBeDefined();
  });

  test("New endpoint works with same data", async () => {
    const oldResponse = await oldApiCall();
    const newResponse = await newApiCall();
    expect(newResponse.data).toEqual(transformOldFormat(oldResponse));
  });
});

Compatibility Helper

// Wrapper per transizione graduale
class MigrationApiWrapper {
  constructor() {
    this.useNewApi = process.env.USE_NEW_API === "true";
  }

  async searchDocuments(kbId, query) {
    if (this.useNewApi) {
      return this.newApi.search(kbId, query);
    } else {
      console.warn("Using deprecated API - migrate to new endpoints");
      return this.oldApi.sppSearch(query);
    }
  }
}

📞 Supporto Migrazione

Per assistenza durante la migrazione:

1. Documentazione: Consulta la nuova documentazione API
2. Migration Tool: Usa il tool di migrazione automatica
3. Support: Contatta il team all'indirizzo migration-support@emblema.ai
4. Community: Unisciti al Discord per sviluppatori

🎯 Benefits della Migrazione

• Performance: +40% miglioramento response time
• Consistency: API unified con pattern consistenti
• Security: Permessi granulari e ownership automatica
• Scalability: Architecture microservizi ottimizzata
• Developer Experience: Documentazione auto-generata e SDK tipizzati