FastComments Java SDK

코딩 에이전트에 FastComments 컨텍스트를 제공하세요 - 위젯, 구성, Secure SSO, REST API 및 SDK:

npx skills add fastcomments/skills

Claude Code, Codex, Cursor, Copilot, Gemini 및 기타 모든 에이전트와 skills CLI에서 지원됩니다.

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 클라이언트 -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>client</artifactId>
        <version>3.1.1</version>
    </dependency>
    
    <!-- 코어 라이브러리 (SSO 포함) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>3.1.1</version>
    </dependency>
    
    <!-- PubSub 라이브러리 (실시간 이벤트용) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>3.1.1</version>
    </dependency>
</dependencies>

Gradle

build.gradle 파일에 Repsy 저장소를 추가합니다:

repositories {
    mavenCentral()
    maven {
        url "https://repo.repsy.io/mvn/winrid/fastcomments"
    }
}

dependencies {
    // API 클라이언트
    implementation "com.fastcomments:client:3.1.1"
    
    // 코어 라이브러리 (SSO 포함)
    implementation "com.fastcomments:core:3.1.1"
    
    // PubSub 라이브러리 (실시간 이벤트용)
    implementation "com.fastcomments:pubsub:3.1.1"
}

라이브러리 구성

이 라이브러리는 세 개의 모듈로 구성되어 있습니다. 생성된 API 클라이언트, API 사용을 더 쉽게 만들어주는 직접 작성된 유틸리티를 포함하는 코어 Java 라이브러리, 그리고 변경 피드를 구독하기 위한 라이브러리인 pubsub 모듈입니다.

• API 클라이언트 라이브러리 문서
• SSO 예제를 포함한 코어 라이브러리 문서
• PubSub 라이브러리 문서

공개 API vs 보안 API

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

ModerationApi는 광범위한 실시간 고속 검토(모더레이션) API 모음을 제공합니다. 모든 ModerationApi 메서드는 sso 파라미터를 받으며, SSO 또는 FastComments.com 세션 쿠키를 통해 인증할 수 있습니다.

인증된 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는 브라우저 세션 내에서 두 번 발생하지 않을 만큼 충분히 고유해야 합니다.