Twenty wurde so entwickelt, dass es entwicklerfreundlich ist und leistungsstarke APIs bietet, die sich an Ihr individuelles Datenmodell anpassen. Wir bieten vier verschiedene API-Typen, um unterschiedlichen Integrationsanforderungen gerecht zu werden.
Entwickler-Erst-Ansatz
Twenty generiert APIs speziell für Ihr Datenmodell:
- Keine langen IDs erforderlich: Verwenden Sie Ihre Objekt- und Feldnamen direkt in Endpunkten
- Standard- und benutzerdefinierte Objekte werden gleich behandelt: Ihre benutzerdefinierten Objekte erhalten dieselbe API-Behandlung wie integrierte
- Dedizierte Endpunkte: Jedes Objekt und Feld erhält seinen eigenen API-Endpunkt
- Benutzerdefinierte Dokumentation: Speziell für das Datenmodell Ihres Arbeitsplatzes generiert
Ihre personalisierte API-Dokumentation ist nach dem Erstellen eines API-Schlüssels unter Einstellungen → API & Webhooks verfügbar. Da Twenty APIs erzeugt, die Ihrem benutzerdefinierten Datenmodell entsprechen, ist die Dokumentation für Ihren Arbeitsbereich einzigartig.
Die beiden API-Typen
Core API
Zugriff auf /rest/ oder /graphql/
Arbeiten Sie mit Ihren tatsächlichen Datensätzen (den Daten):
- Personen, Unternehmen, Opportunities usw. erstellen, lesen, aktualisieren und löschen
- Daten abfragen und filtern
- Verwalten von Datensatzbeziehungen
Zugriff auf /rest/metadata/ oder /metadata/
Verwalten Sie Ihren Arbeitsbereich und Ihr Datenmodell:
- Objekte und Felder erstellen, ändern oder löschen
- Konfigurieren der Arbeitsbereichseinstellungen
- Beziehungen zwischen Objekten definieren
REST vs GraphQL
Sowohl Core- als auch Metadata-APIs sind in REST- und GraphQL-Formaten verfügbar:
| Format | Verfügbare Vorgänge |
|---|
| REST | CRUD, Batch-Vorgänge, Upserts |
| GraphQL | Dasselbe plus Batch-Upserts, Beziehungsabfragen in einem Aufruf |
API-Endpunkte
| Umgebung | Basis-URL |
|---|
| Cloud | https://api.twenty.com/ |
| Selbsthosting | https://{your-domain}/ |
Authentifizierung
Jede API-Anfrage erfordert einen API-Schlüssel im Header:
Authorization: Bearer YOUR_API_KEY
API-Schlüssel erstellen
- Gehen Sie zu Einstellungen → APIs & Webhooks
- Klicken Sie auf + Schlüssel erstellen
- Konfigurieren:
- Name: Beschreibender Name für den Schlüssel
- Ablaufdatum: Wann der Schlüssel abläuft
- Klicken Sie auf Speichern
- Sofort kopieren — der Schlüssel wird nur einmal angezeigt
Ihr API-Schlüssel gewährt Zugriff auf sensible Daten. Teilen Sie ihn nicht mit nicht vertrauenswürdigen Diensten. Wenn er kompromittiert wurde, deaktivieren Sie ihn umgehend und erstellen Sie einen neuen.
Einem API-Schlüssel eine Rolle zuweisen
Für mehr Sicherheit weisen Sie eine spezifische Rolle zu, um den Zugriff zu beschränken:
- Gehen Sie zu Einstellungen → Rollen
- Klicken Sie auf die Rolle, die Sie zuweisen möchten
- Öffnen Sie den Tab Zuweisungen
- Unter API-Schlüssel auf + API-Schlüssel zuweisen klicken
- Wählen Sie den API-Schlüssel aus
Der Schlüssel übernimmt die Berechtigungen dieser Rolle. Siehe Berechtigungen für Details.
API-Schlüssel verwalten
Neu generieren: Einstellungen → APIs & Webhooks → Schlüssel anklicken → Neu generieren
Löschen: Einstellungen → APIs & Webhooks → Schlüssel anklicken → Löschen
API-Playground
Testen Sie Ihre APIs direkt im Browser mit unserem integrierten Playground — verfügbar für REST und GraphQL.
Auf den Playground zugreifen
- Gehen Sie zu Einstellungen → APIs & Webhooks
- API-Schlüssel erstellen (erforderlich)
- Klicken Sie auf REST API oder GraphQL API, um den Playground zu öffnen
Was Sie erhalten
- Interaktive Dokumentation: Für Ihr spezifisches Datenmodell generiert
- Live-Tests: Führen Sie echte API-Aufrufe gegen Ihren Arbeitsbereich aus
- Schema-Explorer: Verfügbare Objekte, Felder und Beziehungen durchsuchen
- Request-Builder: Abfragen mit Autovervollständigung erstellen
Der Playground spiegelt Ihre benutzerdefinierten Objekte und Felder wider, sodass die Dokumentation für Ihren Arbeitsbereich stets korrekt ist.
Batch-Vorgänge
Sowohl REST als auch GraphQL unterstützen Batch-Vorgänge:
- Batch-Größe: Bis zu 60 Datensätze pro Anfrage
- Vorgänge: Mehrere Datensätze erstellen, aktualisieren, löschen
GraphQL-Exklusivfunktionen:
- Batch-Upsert: Erstellen oder Aktualisieren in einem Aufruf
- Verwenden Sie Pluralobjektnamen (z. B.
CreateCompanies statt CreateCompany)
Rate Limits
API-Anfragen werden gedrosselt, um die Stabilität der Plattform zu gewährleisten:
| Limit | Wert |
|---|
| Anfragen | 100 Aufrufe pro Minute |
| Batch-Größe | 60 Datensätze pro Aufruf |
Verwenden Sie Batch-Vorgänge, um den Durchsatz zu maximieren — verarbeiten Sie bis zu 60 Datensätze in einem einzelnen API-Aufruf, statt einzelne Anfragen zu senden.
