Ctrlk
Для когоПеримуществаВозможностиEnterpriseЦены

API Документация

Текущая стабильная документация METEOR APIv3.

Введение

Документация для APIv3 написана в соответствии со спецификацией OpenAPI 3.0. Вы можете просмотреть статическую версию этой документации на веб-сайте или интерактивную версию, представленную с помощью OpenAPI Explorer, в вашей системе METEOR в разделе /api/docs. В последнем случае вы можете опробовать различные конечные точки API, напрямую взаимодействующие с нашими данными METEOR. Кроме того, вы можете получить доступ к самому источнику спецификации в разделах /api/v3/spec.json и /api/v3/spec.yml. .

APIv3 - это REST API для гипермедиа, сокращение от "Гипермедиа как движок состояния приложения" (HATEOAS). Это означает, что каждая конечная точка этого API будет иметь ссылки на другие ресурсы или действия, определенные в результирующем тексте.

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

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

HAL+JSON

HAL - это простой формат, который предоставляет согласованный и простой способ создания гиперссылок между ресурсами в вашем API. Подробнее читайте в следующей спецификации: https://tools.ietf.org/html/draft-kelly-json-hal-08

Реализация API METEOR в формате HAL+JSON обогащает JSON и вводит несколько мета-свойств:

  • _type - указывает тип ресурса (например, рабочий пакет, проект)

  • _links - содержит все ссылки на связанные ресурсы и действия, доступные для данного ресурса

  • _embedded - содержит все внедренные объекты.

HAL не гарантирует, что встроенные ресурсы будут представлены в полном объеме, они также могут быть представлены частично (например, некоторые свойства могут быть опущены). Однако в этом API у вас есть гарантия того, что всякий раз, когда ресурс **внедряется **, он внедряется в своем полном представлении.

Структура ответа API

Все ответы API содержат один объект HAL+JSON, даже коллекции объектов технически представлены одним объектом HAL+JSON, который сам содержит свои элементы. Более подробную информацию о коллекциях можно найти в разделе Коллекции.

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

API поддерживает следующие схемы аутентификации: OAuth2, аутентификацию на основе сеанса и базовую аутентификацию.

В зависимости от настроек экземпляра METEOR многие ресурсы могут быть доступны без проверки подлинности. В случае, если экземпляр требует проверки подлинности для всех запросов, клиент получит код состояния HTTP 401 в ответ на любой запрос.

В противном случае клиенты, не прошедшие проверку подлинности, имеют все разрешения анонимного пользователя.

Проверка подлинности на основе сеанса

Это означает, что вам необходимо войти в METEOR через веб-интерфейс, чтобы пройти аутентификацию в API. Этот метод хорошо подходит для клиентов, работающих в браузере, таких как React-клиент, встроенный в METEOR.

В этом случае вам всегда нужно передавать HTTP-заголовок X-Requested-With "XMLHttpRequest" для аутентификации.

Ключ API через Basic Auth

Пользователи могут проходить аутентификацию в API версии 3, используя basic auth, используя имя пользователя apikey (не логин) и ключ API в качестве пароля. Пользователи могут найти свой ключ API на странице своей учетной записи.

Пример:

Аутентификация # OAuth2.0

METEOR поддерживает аутентификацию и авторизацию с помощью OAuth2 с помощью Потока кода авторизации, а также режимов работы Учетных данных клиента.

Для начала вам сначала необходимо зарегистрировать приложение в разделе администрирования METEOR OAuth вашей установки. Это сохранит запись для вашего приложения с уникальным идентификатором клиента (client_id) и сопутствующим секретным ключом (client_secret).

Затем вы можете использовать одно из следующих руководств для выполнения поддерживаемых процессов OAuth 2.0.:

Почему не использовать имя пользователя и пароль?

Самый простой способ выполнить базовую авторизацию - использовать имя пользователя и пароль естественным образом. Однако в прошлом METEOR уже поддерживал API-ключи для API версии 2, хотя и не через basic auth.

Прямое использование ** имени пользователя и пароля ** будет иметь некоторые преимущества:

  • Это интуитивно понятно для пользователя, которому затем просто нужно будет указать их точно так же, как при входе в METEOR.

  • Никакой дополнительной логики для управления токенами не требуется.

С другой стороны, использование ** ключей API ** также имеет некоторые преимущества, вот почему мы пошли на это:

  • В случае взлома при сохранении на небезопасном клиенте пользователю нужно только повторно создать ключ API, вместо того чтобы менять свой пароль.

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

Самое главное, что у пользователей может не быть пароля для начала. Особенно если они зарегистрировались через провайдера OpenID Connect.

Совместное использование ресурсов разных источников (CORS)

По умолчанию API METEOR не отвечает никакими заголовками CORS. Если вы хотите разрешить междоменные вызовы AJAX для вашего экземпляра METEOR, вам необходимо разрешить возвращаемые заголовки CORS.

Пожалуйста, ознакомьтесь с нашей документацией по настройкам API о том, как выборочно включить CORS.

Разрешенные методы HTTP

  • GET - Получение отдельного ресурса или коллекции ресурсов

  • POST - Создание нового ресурса или выполнение

  • PATCH - Обновление ресурса

  • DELETE - Удаление ресурса

Сжатие

Ответы сжимаются по запросу клиента. В настоящее время поддерживаются gzip и deflate . Клиент сигнализирует о желаемом сжатии, устанавливая заголовок Accept-Encoding. Если заголовок Accept-Encoding не отправлен, предполагается Accept-Encoding: identity, что приведет к тому, что API ответит без сжатия.

Last updated