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.

Using Authenticated APIs (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();

        // REQUIRED: Set your API key (get this from your FastComments dashboard)
        apiClient.setApiKey("YOUR_API_KEY_HERE");

        // Create the API instance with the configured client
        DefaultApi api = new DefaultApi(apiClient);

        // Now you can make authenticated API calls
        try {
            // Example: Add an SSO user
            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: Ошибка валидации запроса
        }
    }
}

Using Public APIs (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();
}

Using Moderation APIs (ModerationApi)

The ModerationApi drives the moderator dashboard. Each method accepts an sso parameter identifying the SSO-authenticated moderator on whose behalf the request is made:

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();
}

Common Issues

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.

Идентификаторы Broadcast

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