Passa al contenuto principale

Migrazione dalle API v1

Questa pagina si rivolge agli integratori con applicazioni costruite sulle API di Askme AI v1 (prefisso /api/*) e descrive come pianificare il passaggio alle API v2 (prefisso /api/v2/*).

A chi si rivolge​

Alle integrazioni realizzate prima della migrazione della piattaforma ad Askme AI v2: chiamate dirette agli endpoint legacy /api/ask, /api/intent, agli analizzatori documentali v1 o alle rotte di supporto (/api/models, /api/auth/user, ...). Le integrazioni già basate su /api/v2/* non sono interessate.

Che cosa cambia​

Sull'installazione v2 è attivo uno strato di compatibilità per il prefisso legacy /api/*:

  • un sottoinsieme di endpoint v1 continua a funzionare e viene servito internamente dai servizi v2; le richieste così instradate vengono marcate con source_app=legacy-v1, in modo che i consumi restino distinguibili da quelli delle integrazioni già migrate;
  • tutti gli altri endpoint v1 rispondono 410 Gone, con intestazioni Sunset/Link e un corpo che indica il percorso di migrazione consigliato.
warning

Lo strato di compatibilità è pensato per la transizione, non come destinazione permanente: le nuove funzionalità (streaming SSE strutturato, output con schema, versionamento agenti, MCP) sono disponibili solo sulle API v2.

Endpoint compatibili​

Endpoint v1 (servito dallo strato di compatibilità)Equivalente v2 consigliato
POST /api/askPOST /api/v2/chat (modalità agente, anche streaming)
POST /api/intentPOST /api/v2/classify
GET /api/auth/userAPI IAM v2 (profilo utente corrente)
GET /api/agentGET /api/v2/agents
GET /api/modelsGET /api/v2/ai/models
GET /api/version, GET /api/health, GET /api/configendpoint di servizio v2 equivalenti
/api/knowledge-bases/*/api/v2/knowledge-bases/*
POST /api/cv_analyzer, POST /api/pdf_analyzer, POST /api/content_analyzerPOST /api/v2/analysis/cv, /analysis/pdf, /analysis/content (oppure le varianti /sync, che restituiscono subito il risultato)
POST /api/pdf_fields, POST /api/pdf_editorPOST /api/v2/analysis/pdf/fields, POST /api/v2/analysis/pdf/edit
note

Le risposte in streaming di POST /api/ask vengono riconfezionate nel formato v1: gli eventi specifici della v2 (ad esempio confidenza e tracciamento RAG) non sono disponibili attraverso lo strato di compatibilità.

Endpoint dismessi​

Qualsiasi rotta /api/* non elencata sopra risponde 410 Gone. Il corpo della risposta e l'intestazione Link indicano la rotta v2 da utilizzare in sostituzione.

Passare le integrazioni a v2​

  1. Generare una chiave API v2 dalla console (Impostazioni › Chiavi API) con gli scope necessari e sostituire il meccanismo di autenticazione v1 con l'intestazione X-Api-Key (si veda Autenticazione).
  2. Sostituire le chiamate agli endpoint legacy con gli equivalenti v2 della tabella, adeguando i payload alla reference per servizio.
  3. Verificare la gestione dello streaming: POST /api/v2/chat emette eventi SSE strutturati, diversi dal formato v1; il testo della risposta arriva negli eventi di tipo content (si veda Risposta in streaming).
  4. Controllare nella sezione Monitoraggio della console i consumi con origine legacy-v1: quando si azzerano, la migrazione delle integrazioni è completa.

Problemi comuni​

  • 410 Gone su un endpoint prima funzionante: l'endpoint non rientra nel sottoinsieme compatibile; utilizzare la rotta v2 indicata nella risposta.
  • Consumi attribuiti a legacy-v1: indicano chiamate che passano ancora dallo strato di compatibilità; individuare l'integrazione e completarne la migrazione.
  • Differenze nel formato di risposta dello streaming: verificare di consumare il formato v1 tramite /api/ask oppure il formato SSE v2 tramite /api/v2/chat, senza mescolare i due.

Pagine correlate​