Java SDK для FastComments

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 Client Library Docs
• Core Library Docs, Including SSO Examples
• PubSub Library Docs

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

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

ModerationApi забезпечує роботу панелі модерації. Він містить методи для модерації коментарів (перелік, підрахунок, пошук, журнали та експорт), дії модерації (видалення/відновлення, позначення, встановлення статусу на перегляд/спам/підтвердження, голоси та повторне відкриття/закриття треду), банів (заборона коментувати, скасування бану, підсумки перед баном, статус бану та налаштування, а також підрахунок заблокованих користувачів) та значків і довіри (нагородження/видалення значка, ручні значки, отримання/встановлення коефіцієнта довіри та внутрішній профіль користувача). Кожен метод ModerationApi приймає параметр sso, щоб виклик можна було виконати від імені модератора, автентифікованого через SSO.

Використання автентифікованих 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();
}

Використання модераційних API (ModerationApi)

Клас ModerationApi керує панеллю модератора. Кожен метод приймає параметр sso, який ідентифікує модератора, автентифікованого через SSO, від імені якого виконується запит:

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

Типові проблеми

1. 401 "missing-api-key" помилка: Переконайтеся, що ви викликаєте apiClient.setApiKey("YOUR_KEY") перед створенням екземпляра DefaultApi.
2. Неправильний клас API: Використовуйте DefaultApi для серверних автентифікованих запитів, PublicApi для клієнтських/публічних запитів.
3. Null API key: SDK мовчки пропустить автентифікацію, якщо API-ключ дорівнює null, що призведе до помилок 401.

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

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