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>3.0.1</version>
    </dependency>
    
    <!-- Core Library (includes SSO) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>3.0.1</version>
    </dependency>
    
    <!-- PubSub Library (for live events) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>3.0.1</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:3.0.1"
    
    // Core Library (includes SSO)
    implementation "com.fastcomments:core:3.0.1"
    
    // PubSub Library (for live events)
    implementation "com.fastcomments:pubsub:3.0.1"
}

Library Contents

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

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

Public vs Secured APIs

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

ModerationApi предоставляет обширный набор быстрых и живых API модерации. Каждый метод ModerationApi принимает параметр sso и может аутентифицироваться через SSO или сессионный cookie FastComments.com.

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 должен быть достаточно уникальным, чтобы не повторяться в рамках одной сессии браузера.