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>1.3.2</version>
    </dependency>

    <!-- Core Library (includes SSO) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>1.3.2</version>
    </dependency>

    <!-- PubSub Library (for live events) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>1.3.2</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:1.3.2"

    // Core Library (includes SSO)
    implementation "com.fastcomments:core:1.3.2"

    // PubSub Library (for live events)
    implementation "com.fastcomments:pubsub:1.3.2"
}

Library Contents

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

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

Public vs Secured APIs

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

Использование аутентифицированных 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();
}

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

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

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

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