Начало работы

Ключевые концепции

Структура API-интерфейса

API-интерфейс Frame.io поддерживает общие концепции, например ограничение частоты запросов, разбивка на страницы для коллекций ресурсов, версионирование и ошибки. В этом разделе описаны особенности каждой из них.

Систематизация и стиль

API-интерфейс систематизирован на основе общих принципов REST. Все запросы должны выполняться через SSL. Все тела запросов и ответов, включая ошибки, кодируются в формате JSON.

Если не указано иное, методы API-интерфейса соответствуют следующим правилам:

  • Свойства без значения будут иметь значение null, а не неопределенное * Для имен атрибутов используется стиль «Snake Case» (например, first_name) * Метки времени отображаются в формате ISO-8601 (например, 2016-02-03T16:38:46.985Z)

Стандарты построения путей

Учетные записи > Команды > Проекты > Ресурсы > Комментарии

В общем случае пути ресурсов в API-интерфейсе Frame.io будут следовать указанной выше иерархической модели в пределах одного родительского уровня. Где это интуитивно понятно, API-интерфейс поддерживает автономные пути ресурсов для объектов, которые логически принадлежат строго одному владельцу.

Например, API-интерфейс Frame.io поддерживает оба следующих пути:

  • GET /accounts/:id/teams — возвращает все команды для учетной записи. * GET /teams — возвращает все команды для выполняющего вызов пользователя. * GET /teams/:id — возвращает сведения о конкретной команде.

Еще один пример: комментарии не имеют большого смысла вне контекста их ресурса, поэтому методы сбора и создания комментариев находятся в области ресурса. Однако при обновлении или удалении комментария контекст ресурса не так важен и опускается из пути ресурса:

  • GET /assets/:id/comments * POST /assets/:id/comments * PUT /comments/:id * DELETE /comments/:id

Области доступа

Независимо от того, получаете ли вы токен через OAuth2.0 или напрямую через Developer Portal, все токены API-интерфейса должны быть связаны с явным списком «областей действия», которые относятся к комбинации ресурса (например, Asset) и действия (например, create) и выражаются точечной нотацией. Например, токен с областью действия asset.create сможет создавать новые ресурсы.

Если вы используете реализацию с токеном разработчика, области действия устанавливаются и назначаются самому токену доступа. Если вы используете приложение OAuth, области действия определяются для приложения, и когда пользователи впервые взаимодействуют с приложением, они соглашаются предоставить приложению разрешение действовать с запрашиваемыми областями.

Доступные области действия для токенов разработчика и приложений включают следующие (обратите внимание, что некоторые области действия доступны не всем, и они отмечены при возникновении проблемы).

Категория области действияОписание
Учетные записи, пользователи и командыПолучите информацию об учетных записях и командах, к которым у вас есть доступ. Если аутентифицированный пользователь является администратором или у него другая роль, он может иметь доступ к информации о дополнительных пользователях и командах в своей учетной записи.

Примечание. Для обновления команд (например, управления веб-перехватчиками) у вас должна быть роль менеджера команды или администратора учетной записи.
Проекты и ресурсыПолучите основную информацию о проектах, проверьте или обновите подписку пользователя, создайте или обновите ресурсы.
КомментарииПолучите, создайте или удалите комментарии к ресурсу или создайте ответы на определенный комментарий.

Примечание. Запросы на обновление или удаление комментариев должны выполняться создателем комментария.
Ссылки для проверкиСоздайте ссылки для рецензирования или управляйте их настройками.

Примечание. Ссылки для рецензирования — это основная функция Frame.io для сбора ресурсов и их отправки для получения отзывов по одному URL-адресу без необходимости явного доступа к команде или проекту.
Веб-перехватчикиВеб-перехватчики предоставляют способ использования событий, происходящих внутри Frame.io, в качестве уведомлений, которые можно отправить во внешние системы для обработки, обратного вызова API-интерфейса и автоматизации рабочих процессов.
Журналы аудитаFrame.io предоставляет журналы для подавляющего большинства действий, выполняемых в его приложениях. Включены как основные операции CRUD с базовыми ресурсами, так и некоторые специальные абстракции (например, AssetVersioned). Для доступа к журналам вы должны быть администратором.
Презентации

Разбивка на страницы

Методы API-интерфейса, которые возвращают коллекцию результатов, всегда разбиваются на страницы. Все методы, которые ожидают результаты с разбивкой на страницы, будут отвечать на следующие параметры запроса и возвращать следующие атрибуты заголовка:

ОписаниеПараметр запросаАтрибут заголовка
Размер страницыpage_sizeper-page
Номер страницыpagepage-number
Количество страницН/Дtotal-pages
Общее количествоН/Дtotal
Кроме того, результаты с разбивкой на страницы будут включать заголовок ответа Link (см. RFC-5988) со следующей информацией:
  • next — соответствующий URL-адрес является ссылкой на следующую страницу.
  • prev — соответствующий URL-адрес является ссылкой на предыдущую страницу.
  • last — соответствующий URL-адрес является ссылкой на последнюю страницу.

Примечание. Когда отсутствуют ссылки next и prev, это указывает на то, что возвращенная первая страница является единственной страницей.