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

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

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

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

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

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

Ця бібліотека містить три модулі. Згенерований клієнт 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. Ідентифікатор має бути достатньо унікальним, щоб не зустрічатися двічі в одній сесії браузера.