{% extends "layout.html" %} {% load static %} {% block title %} API — {{ block.super }} {% endblock %} {% block content %}
🤖
Мои приложения
{% if apps %}
{% for app in apps %} {{ app.name }} {{ app.description }} {% endfor %}
{% else %}
У вас нет ни одного приложения.
Но если вы чувствуете себя программистом — можете создать.
{% endif %}
🤖 API

Наш API еще маленький и глупый, но для простых ботов и интеграций с Клубом его хватает. Основная идея в том, что многие его эндпоинты повторяют обычные URL сайта, но с добавлением .json или .md в конце как расширение. Так легче запомнить.

Если вам нужен новый эндпоинт — вы всегда можете попросить на гитхабе или даже написать его сами. Во славу опенсорса!



Фид и посты

{{ settings.APP_HOST }}/feed.json — вернёт главную страницу в формате JSON Feed. Возможна пажинация. Эндпоинт открыт на публику (это аналог RSS), однако если запрос идёт от неавторизованного пользователя — контент приватных постов будет скрыт.

{{ settings.APP_HOST }}/post/top/feed.json — фид, отфильтрованный по типу постов (all, post, question, thread, ...) и отсортированный по одному из критериев (activity, new, hot, top, top_week, top_month, top_year).

{{ settings.APP_HOST }}/post/2584.json — получить текст и метаданные конкретного поста в том же формате JSON Feed Item.

{{ settings.APP_HOST }}/post/2584.md — вернет текст и заголовок поста в Markdown.

{{ settings.APP_HOST }}/post/2584/comments.json — вернёт список комментов к посту в JSON.



Юзеры

{{ settings.APP_HOST }}/user/{{ request.me.slug }}.json — получить данные юзера по никнейму в Клубе.

{{ settings.APP_HOST }}/user/by_telegram_id/{{ request.me.telegram_id|default:"TG_ID" }}.json — найти юзера по его Telegram ID (не по нику в телеграме, именно по цифровому ID). Удобно для ботов, чтобы проверять зарегистрирован ли пользователь бота в Клубе.

💡 Hint: Чтобы получить данные о себе, можно использовать универсальный юзернейм "me" — {{ settings.APP_HOST }}/user/me.json



Поиск

{{ settings.APP_HOST }}/search/users.json?prefix=vas — найти юзеров по префиксу никнейма. Используется для автокомплита.

{{ settings.APP_HOST }}/search/tags.json?group=collectible — получить теги в группе (collectible, hobbies, personal, club). Можно использовать вместе с ?prefix для автокомплита.

🤖️ Авторизация для ботов

API-запросы к закрытым постам или профилям юзеров требуют авторизации.

Если вы пишете простого бота, вы можете использовать сервис-токен. Он выдаётся один раз при создании приложения и уникален для него. С ним можно делать запросы к API, как будто вы полноценный пользователь.

⛔️ Если сервис-токен утечёт — срочно удаляйте приложение и создавайте новое. Токен специально привязан к автору приложения, чтобы вы сразу заметили, когда ваш аккаунт похакают. Так что храните его в секретах, передавайте через env-переменные и никогда не комитьте в открытые репозитории.

Использовать сервис-токен в запросах можно вот так:

curl -H "X-Service-Token: TOKEN" {{ settings.APP_HOST }}/user/me.json

Для простоты дебага есть второй способ — передавать токен в GET-параметре:

curl {{ settings.APP_HOST }}/user/me.json?service_token=TOKEN

⚠️ Этот способ не рекомендуется для продакшен приложений. GET-параметры имеют свойство утекать через логи сервера или браузера. Используйте его только для собственных нужд.

🪪 OpenID Connect — авторизация людей

Чтобы аутентифицировать конкретных юзеров через Клуб, у нас есть OAuth/OpenID провайдер. Такой способ подойдет, если вы делаете сторонний проект типа Сикрет Санты и хотите сделать кнопку «Войти через Вастрик.Клуб».

Пример можно посмотреть у меня в блоге (вот код).

Протокол стандартный и открытый, так что вы тоже так можете.

Шаг 0. Почитайте как работают OAuth и OpenID Connect, если еще не знакомы с ними.

Шаг 1. Создайте новое приложение. После этого вам дадут Client ID и Secret.

Шаг 2. Теперь отправляйтесь в наш гайд по OpenID в Клубе.

Шаг 3. Вы великолепны. У вас есть классический access_token в формате JWT и им можно авторизовать запросы прямо вот так:

curl -H "Authorization: Bearer ACCESS_TOKEN" {{ settings.APP_HOST }}/user/me.json

👷‍♀️ Код Клуба

Исходный код Клуба открыт на гитхабе: github.com/vas3k/vas3k.club

Можно присылать баги в Issues или даже сразу фиксить их в пулл-реквестах.

Обсуждение разработки и идей — в дев-чате t.me/vas3k_club_dev.

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

Форкать Клуб можно, но на свой страх и риск. Движок Клуба слишком сильно захардкожен под наши нужды, так что проще будет найти что-то универсальное.

{% endblock %}