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 -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>client</artifactId>
        <version>1.3.1</version>
    </dependency>

    <!-- Основна бібліотека (включає SSO) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>1.3.1</version>
    </dependency>

    <!-- Бібліотека PubSub (для подій у реальному часі) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>1.3.1</version>
    </dependency>
</dependencies>

Gradle

Додайте репозиторій Repsy до файлу build.gradle:

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

dependencies {
    // Клієнт API
    implementation "com.fastcomments:client:1.3.1"

    // Основна бібліотека (включає SSO)
    implementation "com.fastcomments:core:1.3.1"

    // Бібліотека PubSub (для подій у реальному часі)
    implementation "com.fastcomments:pubsub:1.3.1"
}

Зміст бібліотеки

Ця бібліотека містить три модулі. Згенерований клієнт API, базова Java-бібліотека, яка містить вручну написані утиліти для спрощення роботи з API, та модуль pubsub, який є бібліотекою для підписки на потоки змін.

• Документація бібліотеки клієнта API
• Документація основної бібліотеки, включно з прикладами SSO
• Документація бібліотеки PubSub

Публічні та захищені API

Для клієнта API є два класи, 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" error: Переконайтеся, що ви викликаєте apiClient.setApiKey("YOUR_KEY") перед створенням екземпляра DefaultApi.
2. Wrong API class: Використовуйте DefaultApi для серверних автентифікованих запитів, PublicApi для клієнтських/публічних запитів.
3. Пустий (null) API-ключ: SDK тихо пропустить автентифікацію, якщо API-ключ дорівнює null, що призведе до помилок 401.

Ідентифікатори трансляцій

Ви побачите, що в деяких викликах API потрібно передавати broadcastId. Коли ви отримуєте події, ви отримаєте назад цей ідентифікатор, щоб знати, що слід ігнорувати подію, якщо ви плануєте оптимістично застосовувати зміни на клієнті (що, ймовірно, варто зробити, оскільки це забезпечує найкращий досвід). Передайте тут UUID. Ідентифікатор має бути достатньо унікальним, щоб не зустрічатися двічі в одній сесії браузера.