Перейти к содержанию
Sursa для разработчиков

GET/v1/catalog/services

Получить список сервисов каталога

list_catalog_services

Возвращает записи глобального каталога внешних сервисов (SaaS и поставщиков): поиск подстроки без учёта регистра в названии, группе или домене сайта, фильтр по категории и пагинация. Общее число по фильтру — в заголовке X-Total-Count. Каталог общий для всех организаций и доступен любому вошедшему пользователю. Его данные поставляются вместе с Sursa и обновляются с каждым выпуском (версия — в GET /v1/catalog/categories и в поле version у icon_url каждой записи).

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

Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.

Параметры запроса

  • qstring | null

    Подстрока названия, группы или домена сайта (без учёта регистра).

    length ≤ 200

  • categorystring | null

    Slug категории (GET /v1/catalog/categories).

  • offsetinteger

    По умолчанию: 0≥ 0

  • limitinteger

    По умолчанию: 50≥ 1, ≤ 500

  • cursorstring

    Курсор следующей страницы из X-Next-Cursor или next_cursor предыдущего ответа с теми же фильтрами; он несёт размер страницы. Вместе с offset — 422 validation.failed; курсор другого списка, других фильтров или испорченный — 400 api.cursor_invalid.

    length ≤ 512

Параметры заголовков

  • X-View-Asstring

    Только для ключей API с ролью admin. Выполняет запрос от имени профиля доступа <profile>[:viewer|verifier|editor], например employee:viewer. Ключ установки этот заголовок использовать не может (403).

Параметры cookie

  • kb_view_asstring

    Cookie режима «Смотреть как» для сессии. POST /auth/view-as устанавливает её, DELETE /auth/view-as — сбрасывает.

Ответы

200Успешный ответ

Заголовки ответа

  • Link

    Адрес следующей страницы, <…>; rel="next". Нет заголовка — это последняя страница.

  • X-Next-Cursor

    Курсор следующей страницы для параметра cursor. Нет заголовка — это последняя страница.

  • X-Total-Count

    Общее число записей, подходящих под фильтр, независимо от limit и offset.

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

array of CatalogService
  • categorystringобязательно

    Slug категории (GET /v1/catalog/categories).

  • description_enstring | nullобязательно

    Краткое описание на английском. null, если описания нет.

  • domainstring | nullобязательно

    Домен сайта без www.. null, если сайта нет.

  • group_namestring | nullобязательно

    Группа (поставщик), если сервис входит в семейство продуктов, например Atlassian; иначе null.

  • iconbooleanобязательно

    Поставляется ли значок вместе с Sursa.

  • icon_urlstring | nullобязательно

    URL значка (/v1/catalog/services/{service_id}/icon?v=… или внешний адрес, настроенный в установке). null, если значка нет.

  • idstring (uuid)обязательно
  • namestringобязательно
  • slugstringобязательно
  • websitestring | nullобязательно

    URL сайта (https://…) или null.

401Учётные данные не переданы (нет ни cookie сессии, ни ключа API) или ключ не найден.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

403Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`detail` — объект с `code: org_suspended | org_deleted`).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

422Ошибка проверки: тело или параметры не соответствуют схеме (`detail` — список ошибок проверки) либо значение параметра вне допустимого диапазона (`detail` — сообщение).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

429Слишком много запросов (`api.rate_limited`), квота организации на минуту, день или месяц исчерпана (`api.quota_exceeded`; в `error.details` — `quota`, `limit` и `reset_at`), достигнут лимит организации или сервис ответов занят (`answers.engine_busy`). Подождите время, указанное в заголовке `Retry-After`.

Заголовки ответа

  • Retry-After

    Сколько секунд подождать перед повтором запроса.

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

Коды ошибок

Коды, которые эта операция может вернуть в error.code, помимо общих кодов любого запроса.

Лимиты частоты

В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.

← catalog · Справочник API