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>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 клиент библиотеката
• Документация на Core библиотеката, включително примери за SSO
• Документация на PubSub библиотеката

Публични и защитени 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 ключ: SDK-то ще пропусне удостоверяването без съобщение, ако API ключът е null, което ще доведе до грешки 401.

Идентификатори на излъчване

Ще видите, че трябва да подадете broadcastId в някои API повиквания. Когато получите събития, ще получите този идентификатор обратно, така че да знаете да игнорирате събитието, ако възнамерявате оптимистично да прилагате промените на клиента (което вероятно ще искате да направите, тъй като осигурява най-доброто потребителско изживяване). Подайте тук UUID. Идентификаторът трябва да е достатъчно уникален, за да не се появи два пъти в рамките на една браузърна сесия.