Twenty was built to be developer-friendly, offering powerful APIs that adapt to your custom data model. Forniamo quattro tipi distinti di API per soddisfare diverse esigenze di integrazione.
Approccio incentrato sullo sviluppatore
Twenty genera API specificamente per il tuo modello di dati, significando:
- Nessun ID lungo richiesto: Utilizza direttamente i nomi degli oggetti e dei campi negli endpoint
- Oggetti standard e personalizzati trattati allo stesso modo: I tuoi oggetti personalizzati ricevono lo stesso trattamento API di quelli predefiniti
- Endpoint dedicati: Ogni oggetto e campo ottiene il proprio endpoint API
- Documentazione personalizzata: Generata specificamente per il modello di dati del tuo workspace
Il tuo API personalizzato genera documentazione personalizzata accessibile tramite Impostazioni → API & Webhooks dopo aver creato una chiave API. Questa documentazione riflette esattamente il tuo modello di dati e le configurazioni dei campi.
I Quattro Tipi di API
Twenty offre API sia in formati REST che GraphQL:
API REST
- Scopo: Gestire la struttura del tuo workspace e modello di dati
- Casi di utilizzo:
- Crea, modifica o elimina oggetti e campi
- Configura le impostazioni del workspace
- Gestire le relazioni del modello di dati
- Accesso: Disponibile tramite endpoint REST
2. API Core REST
- Scopo: Gestire i dati effettivi
- Casi di utilizzo:
- Crea, leggi, aggiorna, elimina record
- Interroga dati specifici
- Gestire le relazioni dei record
- Accesso: Disponibile tramite endpoint REST
API GraphQL
- Scopo: Identico all’API di Metadati REST ma con i benefici di GraphQL
- Casi di utilizzo: Stessa gestione del workspace e del modello di dati
- Benefici addizionali:
- Interroga più tipi di metadati in una richiesta
- Selezione precisa dei campi
- Migliore performance per query complesse
4. API Core GraphQL
- Scopo: Come per l’API Core REST ma con i vantaggi di GraphQL
- Casi di utilizzo: Stessa gestione dei record di dati
- Benefici addizionali:
- Operazioni batch: Disponibile per tutte le operazioni
- Operazioni di upsert: Creare o aggiornare record in una chiamata
- Interrogare le relazioni in richieste singole
- Recupero dati preciso
Operazioni Batch
Supporto Batch di REST e GraphQL
Entrambi gli API REST e GraphQL supportano operazioni batch per la maggior parte delle azioni:
- Dimensione batch: Fino a 60 record per richiesta
- Operazioni disponibili: Creare, aggiornare, eliminare record multipli
- Prestazioni: Significativamente più veloce delle chiamate API individuali
Funzioni Solo-GraphQL
- Batch Upsert: Disponibile solo in API GraphQL
- Utilizzo: Usa nomi di oggetti al plurale (ad es.
CreateCompanies anziché CreateCompany)
- Requisito: Per questo motivo i nomi di oggetti singolari e plurali devono essere distinti
Accesso alla Documentazione API
- Vai a Impostazioni → API & Webhooks
- Crea una chiave API (necessaria per l’accesso alla documentazione)
- Accedi alla tua documentazione personalizzata e sandbox
- Testa gli API con il tuo modello di dati effettivo
La tua documentazione è unica per il tuo workspace perché riflette i tuoi oggetti personalizzati, campi e relazioni.
Quando utilizzare ciascun API
- Imposta il tuo modello di dati
- Crei oggetti o campi personalizzati
- Configuri le impostazioni del workspace
Usa gli API Core quando:
- Gestisci dati quotidiani (Persone, Aziende, Opportunità)
- Integri con sistemi esterni
- Costruisci applicazioni personalizzate
- Automatizzi i flussi di lavoro dei dati
Scegli GraphQL quando:
- Hai bisogno di operazioni batch
- Vuoi minimizzare le chiamate API
- Hai bisogno della funzionalità upsert
- Stai costruendo integrazioni complesse
Scegli REST quando:
- Preferisci una struttura API più semplice
- Stai costruendo integrazioni di base
- Il tuo team è più familiare con REST
- Hai bisogno di semplici operazioni CRUD
Prossimi Passi
- Configurazione API & Webhooks: Impara a creare chiavi API e webhooks
- Documentazione Personalizzata: Accedi alla tua documentazione API personalizzata tramite Impostazioni → API & Webhooks
