FastComments Java SDK

Maven

프로젝트의 POM에 Repsy 저장소를 추가하세요:

<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

build.gradle 파일에 Repsy 저장소를 추가하세요:

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 클라이언트, API 사용을 더 쉽게 해주는 수작업 유틸리티를 포함하는 코어 Java 라이브러리, 그리고 변경 피드를 구독하기 위한 pubsub 모듈입니다.

• API 클라이언트 라이브러리 문서
• Core 라이브러리 문서(SSO 예제 포함)
• PubSub 라이브러리 문서

공개 API vs 보안 API

API 클라이언트에는 DefaultApi, PublicApi, ModerationApi 세 가지 클래스가 있습니다. DefaultApi에는 API 키가 필요한 메서드들이 포함되어 있고, PublicApi에는 브라우저/모바일 기기 등에서 인증 없이 직접 호출할 수 있는 메서드들이 포함되어 있습니다.

ModerationApi는 운영자 대시보드를 구동합니다. 댓글 관리(목록, 카운트, 검색, 로그, 내보내기), 관리 작업(제거/복원, 신고, 검토/스팸/승인 상태 설정, 투표, 스레드 재개/종료), 차단(댓글 차단, 차단 해제, 사전 차단 요약, 차단 상태 및 설정, 차단된 사용자 수) 및 배지와 신뢰도(배지 수여/제거, 수동 배지, 신뢰도 조회/설정, 사용자 내부 프로필)를 위한 메서드를 포함합니다. 모든 ModerationApi 메서드는 sso 파라미터를 허용하므로 호출을 SSO로 인증된 운영자를 대신하여 수행할 수 있습니다.

인증된 API 사용 (DefaultApi)

Important: 인증된 요청을 하기 전에 ApiClient에 API 키를 설정해야 합니다. 설정하지 않으면 요청이 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)

The 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" 오류: DefaultApi 인스턴스를 생성하기 전에 apiClient.setApiKey("YOUR_KEY")를 호출했는지 확인하세요.
2. 잘못된 API 클래스: 서버 쪽 인증된 요청에는 DefaultApi를 사용하고, 클라이언트/공개 요청에는 PublicApi를 사용하세요.
3. API 키가 null인 경우: SDK는 API 키가 null이면 인증을 조용히 건너뛰어 401 오류를 발생시킵니다.

브로드캐스트 ID

일부 API 호출에서 broadcastId를 전달해야 한다는 것을 보게 됩니다. 이벤트를 수신하면 이 ID가 반환되므로, 클라이언트에서 낙관적으로 변경을 적용하려는 경우 이벤트를 무시해야 하는지 알 수 있습니다 (더 나은 사용자 경험을 제공하므로 아마 그렇게 하게 될 것입니다). 여기에 UUID를 전달하세요. 이 ID는 브라우저 세션 내에서 두 번 발생하지 않을 만큼 충분히 고유해야 합니다.