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"
}

Library Contents

Тази библиотека съдържа три модула. Генерираният API клиент, основната Java библиотека, която съдържа ръчно написани помощни средства за улесняване на работата с API-то, и модула pubsub, който е библиотека за абониране за потоци от промени.

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

Public vs Secured APIs

За 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) {
        // Създайте и конфигурирайте ApiClient
        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 key: SDK-то ще пропусне автентикацията без съобщение, ако API ключът е null, което води до грешки 401.

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

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