Twenty разработан для удобства разработчиков и предлагает мощные API, которые адаптируются к вашей пользовательской модели данных. Мы предоставляем четыре различных типа API, чтобы удовлетворить различные интеграционные потребности.
Подход, ориентированный на разработчиков
Twenty генерирует API специально для вашей модели данных:
- Длинные ID не требуются: используйте названия объектов и полей прямо в конечных точках.
- Стандартные и пользовательские объекты обрабатываются одинаково: ваши пользовательские объекты получают такой же доступ к API, как и встроенные.
- Выделенные конечные точки: каждый объект и поле получают свою собственную конечную точку API.
- Пользовательская документация: генерируется специально для модели данных вашего рабочего пространства.
Персонализированная документация по вашему API доступна в разделе Настройки → API и вебхуки после создания ключа API. Поскольку Twenty генерирует API, соответствующие вашей пользовательской модели данных, документация уникальна для вашего рабочего пространства.
Два типа API
Основной API
Доступен на /rest/ или /graphql/
Работайте с реальными записями (данными):
- Создавайте, читайте, обновляйте и удаляйте People, Companies, Opportunities и т. д.
- Запрашивайте и фильтруйте данные
- Управление отношениями записей.
API метаданных
Доступен на /rest/metadata/ или /metadata/
Управляйте своим рабочим пространством и моделью данных:
- Создание, изменение или удаление объектов и полей.
- Настройка параметров рабочего пространства.
- Определяйте связи между объектами
REST против GraphQL
И Core, и Metadata API доступны в форматах REST и GraphQL:
| Формат | Доступные операции |
|---|
| REST | CRUD, пакетные операции, upsert-операции |
| GraphQL | То же самое + пакетные upsert-операции, запросы связей за один вызов |
Конечные точки API
| Среда | Базовый URL |
|---|
| Облако | https://api.twenty.com/ |
| Самостоятельный хостинг | https://{your-domain}/ |
Аутентификация
Каждый запрос к API требует ключ API в заголовке:
Authorization: Bearer YOUR_API_KEY
Создать ключ API
- Перейдите в Настройки → API и Вебхуки
- Нажмите + Создать ключ
- Настроить:
- Имя: описательное название для ключа
- Дата истечения: когда истекает срок действия ключа
- Нажмите Сохранить
- Скопируйте сразу — ключ показывается только один раз
Ваш ключ API предоставляет доступ к конфиденциальным данным. Не делитесь им с ненадежными сервисами. Если он скомпрометирован, немедленно отключите его и создайте новый.
Назначить роль ключу API
Для повышения безопасности назначьте конкретную роль, чтобы ограничить доступ:
- Перейдите в Настройки → Роли
- Нажмите на роль, которую хотите назначить
- Откройте вкладку Назначение
- В разделе Ключи API нажмите + Назначить ключу API
- Выберите ключ API
Ключ унаследует разрешения этой роли. См. Разрешения для подробностей.
Управление API-ключами
Сгенерировать заново: Настройки → API и вебхуки → Нажмите ключ → Сгенерировать заново
Удалить: Настройки → API и вебхуки → Нажмите ключ → Удалить
Песочница API
Тестируйте свои API прямо в браузере с нашей встроенной песочницей — доступной как для REST, так и для GraphQL.
Доступ к песочнице
- Перейдите в Настройки → API и Вебхуки
- Создайте ключ API (обязательно)
- Нажмите на REST API или GraphQL API, чтобы открыть песочницу
Что вы получаете
- Интерактивная документация: генерируется для вашей конкретной модели данных
- Тестирование в реальном времени: выполняйте реальные вызовы API к вашему рабочему пространству
- Обозреватель схемы: просматривайте доступные объекты, поля и связи
- Конструктор запросов: создавайте запросы с автодополнением
Песочница отражает ваши пользовательские объекты и поля, поэтому документация всегда точна для вашего рабочего пространства.
Пакетные операции
И REST, и GraphQL поддерживают пакетные операции:
- Размер пакета: до 60 записей на запрос.
- Операции: создание, обновление, удаление нескольких записей
Функции только для GraphQL:
- Пакетный upsert: создание или обновление за один вызов
- Используйте имена объектов во множественном числе (например,
CreateCompanies вместо CreateCompany)
Лимиты скорости
Запросы к API ограничиваются для обеспечения стабильности платформы:
| Лимит | Значение |
|---|
| Запросы | 100 запросов в минуту |
| Размер пакета | 60 записей за один запрос |
Используйте пакетные операции, чтобы максимизировать пропускную способность — обрабатывайте до 60 записей за один запрос API вместо выполнения отдельных запросов.
