FastComments Java SDK

Maven

Добавьте репозиторий Repsy в POM вашего проекта:

<repositories>
    <repository>
        <id>repsy</id>
        <name>FastComments Maven Repository on Repsy</name>
        <url>https://repo.repsy.io/mvn/winrid/fastcomments</url>
    </repository>
</repositories>

Затем добавьте необходимые зависимости:

<dependencies>
    <!-- API Client -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>client</artifactId>
        <version>2.0.0</version>
    </dependency>
    
    <!-- Core Library (includes SSO) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>2.0.0</version>
    </dependency>
    
    <!-- PubSub Library (for live events) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>2.0.0</version>
    </dependency>
</dependencies>

Gradle

Добавьте репозиторий Repsy в файл build.gradle:

repositories {
    mavenCentral()
    maven {
        url "https://repo.repsy.io/mvn/winrid/fastcomments"
    }
}

dependencies {
    // API Client
    implementation "com.fastcomments:client:2.0.0"
    
    // Core Library (includes SSO)
    implementation "com.fastcomments:core:2.0.0"
    
    // PubSub Library (for live events)
    implementation "com.fastcomments:pubsub:2.0.0"
}

Содержимое библиотеки

Эта библиотека содержит три модуля. Сгенерированный API-клиент, основная Java-библиотека, которая содержит вручную написанные утилиты для упрощения работы с API, и модуль pubsub, который является библиотекой для подписки на ленты изменений.

• Документация библиотеки API-клиента
• Документация основной библиотеки, включая примеры SSO
• Документация библиотеки PubSub

Публичные и защищённые API

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

ModerationApi отвечает за панель модератора. Он содержит методы для модерации комментариев (просмотр списка, подсчёт, поиск, журналы и экспорт), действий модерации (удаление/восстановление, пометка, установка статусов на проверку/спам/одобрение, голоса и повторное открытие/закрытие треда), блокировок (запрет на комментирование, отмена бана, сводки перед баном, статус и настройки бана, и количество заблокированных пользователей), а также значков и доверия (назначение/удаление значка, ручные значки, получение/установка коэффициента доверия и внутренний профиль пользователя). Каждый метод ModerationApi принимает параметр sso, чтобы вызов можно было выполнить от имени модератора, аутентифицированного через SSO.

Использование аутентифицированных API (DefaultApi)

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

import com.fastcomments.invoker.ApiClient;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.api.DefaultApi;
import com.fastcomments.model.*;

public class Example {
    public static void main(String[] args) {
        // Создаём и настраиваем API-клиент
        ApiClient apiClient = new ApiClient();

        // ОБЯЗАТЕЛЬНО: Установите ваш API-ключ (возьмите его из панели управления FastComments)
        apiClient.setApiKey("YOUR_API_KEY_HERE");

        // Создаём экземпляр API с настроенным клиентом
        DefaultApi api = new DefaultApi(apiClient);

        // Теперь вы можете выполнять аутентифицированные вызовы API
        try {
            // Пример: Добавить SSO-пользователя
            CreateAPISSOUserData userData = new CreateAPISSOUserData();
            userData.setId("user-123");
            userData.setEmail("user@example.com");
            userData.setDisplayName("John Doe");

            AddSSOUserAPIResponse response = api.addSSOUser("YOUR_TENANT_ID", userData)
                .execute();
            System.out.println("User created: " + response);

        } catch (ApiException e) {
            System.err.println("Error: " + e.getResponseBody());
            // Распространённые ошибки:
            // - 401: API-ключ отсутствует или недействителен
            // - 400: Ошибка валидации запроса
        }
    }
}

Использование публичных API (PublicApi)

Публичные эндпоинты не требуют аутентификации:

import com.fastcomments.api.PublicApi;
import com.fastcomments.invoker.ApiException;

PublicApi publicApi = new PublicApi();

try {
    var response = publicApi.getCommentsPublic("YOUR_TENANT_ID", "page-url-id")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

Использование API модерации (ModerationApi)

ModerationApi обеспечивает работу панели модератора. Каждый метод принимает параметр sso, который идентифицирует модератора, аутентифицированного через SSO, от имени которого выполняется запрос:

import com.fastcomments.api.ModerationApi;
import com.fastcomments.invoker.ApiException;
import com.fastcomments.model.*;

ModerationApi moderationApi = new ModerationApi();

try {
    // Список комментариев, ожидающих модерации
    ModerationAPIGetCommentsResponse response = moderationApi.getApiComments()
        .sso("YOUR_SSO_TOKEN")
        .execute();
    System.out.println(response);
} catch (ApiException e) {
    e.printStackTrace();
}

Распространённые проблемы

1. 401 "missing-api-key" error: Убедитесь, что вы вызываете apiClient.setApiKey("YOUR_KEY") перед созданием экземпляра DefaultApi.
2. Wrong API class: Используйте DefaultApi для серверных аутентифицированных запросов, PublicApi для клиентских/публичных запросов.
3. Null API key: SDK тихо пропустит аутентификацию, если API-ключ равен null, что приведёт к ошибкам 401.

Идентификаторы трансляций

Вы увидите, что в некоторых вызовах API нужно передавать broadcastId. Когда вы получаете события, этот идентификатор возвращается, поэтому вы сможете игнорировать событие, если собираетесь оптимистично применять изменения на клиенте (что, вероятно, вы и захотите сделать, поскольку это обеспечивает наилучший опыт). Передайте здесь UUID. Идентификатор должен быть достаточно уникальным, чтобы не появляться дважды в одной сессии браузера.