FastComments Java SDK

Maven

Aggiungi il repository Repsy al POM del tuo progetto:

<repositories>
    <repository>
        <id>repsy</id>
        <name>FastComments Maven Repository on Repsy</name>
        <url>https://repo.repsy.io/mvn/winrid/fastcomments</url>
    </repository>
</repositories>

Aggiungi quindi le dipendenze necessarie:

<dependencies>
    <!-- Client API -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>client</artifactId>
        <version>0.0.2</version>
    </dependency>

    <!-- Libreria Core (include SSO) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>core</artifactId>
        <version>0.0.2</version>
    </dependency>

    <!-- Libreria PubSub (per eventi in tempo reale) -->
    <dependency>
        <groupId>com.fastcomments</groupId>
        <artifactId>pubsub</artifactId>
        <version>0.0.2</version>
    </dependency>
</dependencies>

Gradle

Aggiungi il repository Repsy al file build.gradle:

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

dependencies {
    // Client API
    implementation "com.fastcomments:client:0.0.2"

    // Libreria Core (include SSO)
    implementation "com.fastcomments:core:0.0.2"

    // Libreria PubSub (per eventi in tempo reale)
    implementation "com.fastcomments:pubsub:0.0.2"
}

Contenuti della libreria

Questa libreria contiene tre moduli. Il client API generato, la libreria Java core che contiene utility scritte a mano per semplificare il lavoro con l'API, e il modulo pubsub che è una libreria per iscriversi ai feed delle modifiche.

• Documentazione della libreria Client API
• Documentazione della libreria Core, inclusi esempi SSO
• Documentazione della libreria PubSub

API pubbliche vs protette

Per il client API, ci sono due classi, DefaultApi e PublicApi. DefaultApi contiene metodi che richiedono la tua chiave API, e PublicApi contiene chiamate API che possono essere effettuate direttamente da un browser/dispositivo mobile/etc. senza autenticazione.

Uso delle API Autenticate (DefaultApi)

Importante: Devi impostare la tua API key su ApiClient prima di effettuare richieste autenticate. Se non lo fai, le richieste restituiranno un errore 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) {
        // Crea e configura il client API
        ApiClient apiClient = new ApiClient();

        // OBBLIGATORIO: Imposta la tua API key (prendila dalla dashboard di FastComments)
        apiClient.setApiKey("YOUR_API_KEY_HERE");

        // Crea l'istanza dell'API con il client configurato
        DefaultApi api = new DefaultApi(apiClient);

        // Ora puoi effettuare chiamate API autenticate
        try {
            // Esempio: Aggiungi un utente 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());
            // Errori comuni:
            // - 401: la API key manca o non è valida
            // - 400: la validazione della richiesta è fallita
        }
    }
}

Uso delle API Pubbliche (PublicApi)

Gli endpoint pubblici non richiedono autenticazione:

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

Problemi Comuni

1. 401 "missing-api-key" error: Assicurati di chiamare apiClient.setApiKey("YOUR_KEY") prima di creare l'istanza DefaultApi.
2. Wrong API class: Usa DefaultApi per richieste autenticate lato server, PublicApi per richieste lato client/pubbliche.
3. Null API key: L'SDK salterà silenziosamente l'autenticazione se l'API key è null, portando a errori 401.

ID di broadcast

Vedrai che dovrai passare un broadcastId in alcune chiamate API. Quando riceverai eventi, ti verrà restituito questo ID, così saprai di ignorare l'evento se prevedi di applicare le modifiche in modo ottimistico sul client (probabilmente vorrai farlo, perché offre la migliore esperienza). Passa un UUID qui. L'ID dovrebbe essere sufficientemente unico da non ripetersi due volte durante una sessione del browser.