Перейти к основному содержанию

​
API с отдельной схемой для каждого тенанта

Для Twenty нет статической документации по API. У каждого рабочего пространства своя схема — когда вы добавляете пользовательский объект (например, Invoice), он сразу получает эндпоинты REST и GraphQL, идентичные встроенным объектам, таким как Company или Person. API генерируется из схемы, поэтому эндпоинты напрямую используют названия ваших объектов и полей — никаких непрозрачных идентификаторов. Документация по API для вашего рабочего пространства доступна в разделе Настройки → Разработчики → API после создания ключа API. Она включает интерактивную песочницу, где вы можете выполнять реальные вызовы к своим данным.

​
Два API

Основное API — /rest/ и /graphql/ CRUD над записями: Люди, Компании, Сделки, ваши пользовательские объекты. Запросы, фильтрация, переход по связям. API метаданных — /rest/metadata/ и /metadata/ Управление схемой: создание/изменение/удаление объектов, полей и связей. Так вы программно изменяете свою модель данных. Оба доступны как REST и GraphQL. GraphQL добавляет пакетные upsert-операции и возможность переходить по связям в одном запросе. В обоих случаях используются одни и те же базовые данные.

​
Базовые URL-адреса

​
Аутентификация

Создайте ключ API в Настройки → Разработчики → API → + Создать ключ. Сразу скопируйте его — он показывается только один раз. Ключам можно задать область действия для конкретной роли в разделе Settings → Members → Roles → Assignment tab, чтобы ограничить их доступ. Для доступа на основе OAuth (внешние приложения, действующие от имени пользователей), см. OAuth.

​
Пакетные операции

И REST, и GraphQL поддерживают пакетную обработку до 60 записей за один запрос — создание, обновление или удаление. GraphQL также поддерживает пакетный upsert (создание или обновление за один вызов), используя имена во множественном числе, например CreateCompanies.

​
Выбор полей (REST)

Конечные точки записей REST принимают параметр запроса fields, чтобы возвращать только нужные поля:
  • id всегда возвращается.
  • Составные поля (например, emails или name) выбираются целиком по имени поля.
  • Поле отношения «многие к одному» возвращает свой столбец соединения (например, companyId) с depth=0. Поля отношения «один ко многим» возвращаются только с depth=1. При depth=1 разворачиваются только поля связей, перечисленные в fields.
  • Неизвестные поля или поля, которые ваша роль не может читать, возвращают ошибку 400.
Если fields не указан для объекта с более чем 200 доступными для чтения полями, каждая запись возвращает набор из 200 полей по умолчанию: id, поля идентификатора метки и изображения, createdAt, updatedAt, deletedAt, position, затем стандартные поля перед пользовательскими полями, упорядоченные по имени. Явно передайте fields, чтобы прочитать любое поле за пределами этого набора по умолчанию.

​
Лимиты скорости