Twenty разработан для удобства разработчиков и предлагает мощные API, которые адаптируются к вашей пользовательской модели данных. Мы предоставляем четыре различных типа API, чтобы удовлетворить различные интеграционные потребности.
Developer-First Approach
Twenty генерирует API специально для вашей модели данных, то есть:
- Длинные ID не требуются: используйте названия объектов и полей прямо в конечных точках.
- Standard and custom objects treated equally: Your custom objects get the same API treatment as built-in ones
- Выделенные конечные точки: каждый объект и поле получают свою собственную конечную точку API.
- Пользовательская документация: генерируется специально для модели данных вашего рабочего пространства.
Ваш пользовательский API генерирует персонализированную документацию, доступную через Настройки → API и вебхуки после создания ключа API. Эта документация отражает вашу точную модель данных и конфигурацию полей.
Четыре типа API
Twenty предлагает API в форматах REST и GraphQL.
REST API
- Цель: управление рабочим пространством и структурой модели данных.
- Сценарии использования:
- Создание, изменение или удаление объектов и полей.
- Настройка параметров рабочего пространства.
- Управление отношениями модели данных.
- Доступ: доступно через конечные точки REST.
2. REST Core API
- Цель: управление вашими фактическими записями данных.
- Сценарии использования:
- Создание, чтение, обновление, удаление записей.
- Запрос конкретных данных.
- Управление отношениями записей.
- Доступ: доступно через конечные точки REST.
GraphQL API
3. GraphQL Метаданные API
- Purpose: Same as REST Metadata API but with GraphQL benefits
- Сценарии использования: то же управление рабочим пространством и моделью данных.
- Дополнительные преимущества:
- Запрос нескольких типов метаданных в одном запросе.
- Точный выбор полей.
- Лучшая производительность для сложных запросов.
4. GraphQL Основной API
- Цель: то же, что и у REST Основной API, но с победениями GraphQL.
- Сценарии использования: то же управление записями данных.
- Дополнительные преимущества:
- Управляемые операции партиями: доступны для всех операций.
- Операции “Вставка” и “Обновление”: создать или обновить записи за один вызов.
- Запросить отношения в одиночных запросах.
- Точное извлечение данных.
Пакетные операции
Поддержка пакетных операций в REST и GraphQL
Обе REST и GraphQL API поддерживают пакетные операции для большинства действий:
- Размер пакета: до 60 записей на запрос.
- Доступные операции: создание, обновление, удаление множественных записей.
- Производительность: значительно быстрее, чем индивидуальные вызовы API.
Функции только для GraphQL
- Пакетное обновление и вставка: доступно только в GraphQL API.
- Использование: используйте имена объектов во множественном числе (например,
CreateCompanies вместо CreateCompany).
- Требование: именно поэтому имена объектов в единственном и множественном числе должны быть различными.
Доступ к документации API
- Перейдите в Настройки → API и вебхуки.
- Создайте ключ API (обязательно для доступа к документации).
- Получите доступ к вашей персонализированной документации и среде тестирования.
- Тестируйте API с вашей фактической моделью данных.
Ваша документация уникальна для вашего рабочего пространства, поскольку она отражает ваши пользовательские объекты, поля и отношения.
Когда использовать каждый API
Используйте Метаданные API, когда:
- Настраиваете модель данных.
- Создаете пользовательские объекты или поля.
- Настраиваете параметры рабочего пространства.
Используйте Основные API, когда:
- Управляете данными на ежедневной основе (Люди, Компании, Возможности).
- Интегрируетесь с внешними системами.
- Создаете пользовательские приложения.
- Автоматизируете рабочие процессы данных.
Выберите GraphQL, когда:
- Вам нужны пакетные операции.
- Вы хотите минимизировать количество вызовов API.
- Вам нужны функции вставки и обновления.
- Вы создаете сложные интеграции.
Выберите REST, когда:
- Вы предпочитаете более простую структуру API.
- Вы создаете базовые интеграции.
- Ваша команда больше знакома с REST.
- Вам нужны простые операции CRUD.
Следующие шаги
- API & Webhooks Setup: Learn how to create API keys and webhooks
- Пользовательская документация: Получите доступ к вашей персонализированной документации API через Настройки → API и вебхуки.
