Разработчикам
Создавайте с Welley
С помощью Welley API можно создавать клиенты, скрипты, инструменты для сообществ и интеграции. Актуальная документация Swagger описывает доступные операции и схемы.
В будущем мы планируем выпустить Welley с открытым исходным кодом. Дата выпуска и лицензия пока не объявлены.
Начните с публичного запроса
API работает по HTTPS, и большинство операций принимают и возвращают JSON. Публичные операции чтения могут работать без аккаунта.
Получите сведения о сервере
Этот запрос возвращает публичные метаданные сервера. Данные сервера он не меняет.
curl --fail --silent --show-error "https://welley.social/api/v1/instance"Найдите операцию в Swagger
Прежде чем писать клиент, проверьте параметры операции, схемы запроса и ответа и разрешения.
Аутентификация интеграции
Защищённым операциям нужен действительный токен в заголовке Authorization. Наш официальный CLI отправляет токен с префиксом Bearer.
Прочитайте свои действующие разрешения на сервере
Задайте в WELLEY_TOKEN свой действительный токен так, как вы обычно обращаетесь с секретами. Этот пример только читает данные.
curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"- Для интеграции создайте персональный токен доступа в настройках аккаунта.
- Задайте ему имя и срок действия. API также принимает expiresInDays=0 для токена без сохранённого срока действия.
- Ограничьте, какие глобальные разрешения, разрешения групп и какие группы может использовать токен.
- Если оставить список разрешённых значений пустым, это поле ограничено только вашим текущим доступом. Токен не может дать права, которых нет у вас.
- Секрет токена вы увидите только один раз. Сохраните его, прежде чем закроете результат создания.
- Для управления токенами нужна сессия входа в аккаунт. Персональный токен доступа не может создавать, перечислять, копировать или отзывать токены.
Проверьте разрешения и область действия
Аутентификация сообщает API, кто обращается. Разрешения роли определяют, какими операциями может пользоваться эта вызывающая сторона.
- API возвращает 401, если у защищённого запроса нет действительной аутентификации.
- API возвращает 403, если у вызывающей стороны нет нужного разрешения.
- Имена разрешений имеют вид Resource.Action, например GroupSettings.Manage.
- Для операций с вебхуками и разрешениями, привязанных к области, опустите scope, чтобы использовать область сервера. Для области группы передайте TypeId группы.
- Читайте описание каждой операции. Некоторые конечные точки используют HTTP-подписи или другой протокол вместо токена аккаунта.
Выберите область API
Справочник охватывает социальные функции, интеграции и администрирование сервера. Примеры здесь составляют лишь малую часть API.
Аккаунты и профили
Читайте профили, управляйте идентичностями аккаунта и используйте операции экспорта и переноса аккаунта.
| Метод | Путь | Операция | Доступ |
|---|---|---|---|
| GET | /api/v1/users | Прочитать локальный или удалённый профиль по имени пользователя. | Открытый доступ или необязательный токен |
| POST | /api/v1/users | Добавьте ещё один профиль в текущий аккаунт, в пределах лимита сервера. | Нужен токен |
Публикации и ленты
Читайте ленты и создавайте публикации. Другие операции работают с ответами, опросами, реакциями, черновиками и сохранёнными публикациями.
| Метод | Путь | Операция | Доступ |
|---|---|---|---|
| GET | /api/v1/posts | Читайте публичные публикации как гость или персональную ленту после аутентификации. | Открытый доступ или необязательный токен |
| POST | /api/v1/posts | Создайте публикацию с её содержимым и указанием, кто может её видеть. | Нужен токен |
Группы и события
Создавайте инструменты для сообществ на основе групп, участия в них, каналов, модерации и событий.
| Метод | Путь | Операция | Доступ |
|---|---|---|---|
| POST | /api/v1/groups | Создайте группу с разрешениями аутентифицированного пользователя. | Нужен токен |
| GET | /api/v1/events | Получите список публичных событий или событий, которые видит аутентифицированный пользователь. | Открытый доступ или необязательный токен |
| POST | /api/v1/events | Создайте событие. Для события группы нужно разрешение GroupEvents.Create. | Нужен токен |
Беседы и уведомления
Читайте комнаты бесед и их сообщения. Читайте коллекции уведомлений и обновляйте их статус прочтения.
| Метод | Путь | Операция | Доступ |
|---|---|---|---|
| GET | /api/v1/rooms | Список комнат текущего пользователя. Чтобы продолжить список, используйте nextCursor из тела ответа. | Нужен токен |
| GET | /api/v1/user-notifications | Список уведомлений текущего пользователя. | Нужен токен |
Медиа, поиск и перевод
Загружайте медиа, ищите среди видимого вам содержимого и запрашивайте переводы текста.
| Метод | Путь | Операция | Доступ |
|---|---|---|---|
| POST | /api/v1/uploads | Создайте запись загрузки, а затем отправьте содержимое файла методом PUT на URL загрузки, который она возвращает. | Нужен токен |
| GET | /api/v1/search | Ищите среди содержимого, которое видно вызывающей стороне, или разрешайте поддерживаемые URL. | Открытый доступ или необязательный токен |
| POST | /api/v1/translate/text | Переведите текст на запрошенный язык. | Нужен токен |
Вебхуки и ИИ-агенты
Подключайте внешние сервисы через вебхуки. Настраивайте ИИ-агентов через API агентов.
| Метод | Путь | Операция | Доступ |
|---|---|---|---|
| GET | /api/v1/webhooks/events | Получите список поддерживаемых типов событий вебхуков. | Нужен токен |
| POST | /api/v1/webhooks | Создайте вебхук в области сервера или группы, на которую у вас есть разрешение. Секрет HTTP-подписи показывается только один раз. | Нужен токен |
| GET | /api/v1/ai-agents | Список ИИ-агентов, которые видны вызывающей стороне. | Нужен токен |
Администрирование сервера и групп
Используйте API для настроек, жалоб, модерации, управления федерацией, квот и администрирования развёртывания.
| Метод | Путь | Операция | Доступ |
|---|---|---|---|
| GET | /api/v1/rbac/permissions | Прочитайте действующие разрешения для текущего пользователя и области. | Нужен токен |
| GET | /api/v1/settings | Прочитайте настройки платформы, если у аккаунта есть нужные разрешения. | Открытый доступ или необязательный токен |
Обработка ответов и медиа
Следуйте постраничной навигации и порядку загрузки, которые описаны у каждой операции.
- Для лент с курсорами переходите по ссылкам пагинации, которые возвращает сервер. Не составляйте курсоры, угадывая ID.
- Комнаты возвращают непрозрачный nextCursor в теле ответа. Когда продолжаете список, оставляйте те же фильтры.
- Чтобы загрузить медиа, создайте запись загрузки, а затем отправьте содержимое на URL, который она возвращает.
- Проверяйте ответы с ошибками и лимиты каждой операции. Даже для описанной в документации операции может понадобиться роль, конфигурация сервера или внешний провайдер.