fastcomments-nim

The FastComments Nim SDK. You can use this to build secure and scalable backend applications that interact with FastComments, or build reactive client applications.

Requirements

• Nim >= 1.6.0
• nimcrypto >= 0.5.4

Installation

Using Nimble

nimble install fastcomments

Building from Source

nimble build

Library Contents

This library contains the generated API client and the SSO utilities to make working with the API easier.

• API Client Library Docs

Public vs Secured APIs

For the API client, there are three API modules, api_default, api_public, and api_moderation. The api_default contains methods that require your API key, and api_public contains api calls that can be made directly from a browser/mobile device/etc without authentication. The api_moderation module contains methods for the moderator dashboard.

The api_moderation module provides an extensive suite of live and fast moderation APIs. Every api_moderation method accepts an sso parameter and can authenticate via SSO or a FastComments.com session cookie.

Quick Start

Using Authenticated APIs (DefaultAPI)

Important: Authenticated endpoints require your API key to be set as the x-api-key header.

import httpclient
import fastcomments
import fastcomments/apis/api_default
import fastcomments/models/model_comment_data

let client = newHttpClient()
client.headers["x-api-key"] = "your-api-key"

# Make authenticated API calls.
# Required parameters (and the request body) are positional; optional
# parameters are passed via the operation's options object.
let (response, httpResponse) = getComments(
  httpClient = client,
  tenantId = "your-tenant-id",
  options = GetCommentsOptions(
    urlId: "your-url-id",
    direction: SortDirections.DESC
  )
)

if response.isSome:
  let resp = response.get()
  if resp.comments.isSome:
    echo "Found ", resp.comments.get().len, " comments"

Using Public APIs (PublicAPI)

Public endpoints don't require authentication:

import httpclient
import fastcomments
import fastcomments/apis/api_public

let client = newHttpClient()

# Make public API calls.
# tenantId and urlId are required (positional); everything else is optional.
let (response, httpResponse) = getCommentsPublic(
  httpClient = client,
  tenantId = "your-tenant-id",
  urlId = "your-url-id",
  options = GetCommentsPublicOptions(
    direction: SortDirections.DESC
  )
)

if response.isSome:
  let resp = response.get()
  if resp.comments.isSome:
    echo "Found ", resp.comments.get().len, " comments"

Using Moderation APIs (ModerationAPI)

Moderation endpoints power the moderator dashboard and are authenticated with an SSO token for the acting moderator:

import httpclient
import fastcomments
import fastcomments/apis/api_moderation

let client = newHttpClient()

# List comments in the moderation dashboard.
# This operation has no required parameters, so everything is optional.
let (response, httpResponse) = getApiComments(
  httpClient = client,
  options = GetApiCommentsOptions(
    count: 30,
    tenantId: "your-tenant-id",
    sso: "your-sso-token"
  )
)

if response.isSome:
  let resp = response.get()
  echo "Found ", resp.comments.len, " comments"

Common Issues

1. 401 authentication error: Make sure you set the x-api-key header on your HttpClient before making DefaultAPI requests: client.headers["x-api-key"] = "your-api-key"
2. Wrong API class: Use api_default for server-side authenticated requests, api_public for client-side/public requests, and api_moderation for moderator dashboard requests.

Making API Calls

All API methods in this SDK return tuples of (Option[ResponseType], Response). The first element contains the parsed response if successful, and the second element is the raw HTTP response.

Required parameters and the request body are passed positionally. The remaining optional parameters are collected into a single Api<Operation>Options object, which is the last argument. Operations with no optional parameters take no options object.

Example: Fetching Comments

import httpclient
import options
import fastcomments
import fastcomments/apis/api_default

let client = newHttpClient()
client.headers["x-api-key"] = "your-api-key"

let (response, httpResponse) = getComments(
  httpClient = client,
  tenantId = "your-tenant-id",
  options = GetCommentsOptions(
    urlId: "your-url-id",
    direction: SortDirections.DESC
  )
)

if httpResponse.code == Http200:
  if response.isSome:
    let resp = response.get()
    if resp.comments.isSome:
      echo "Found ", resp.comments.get().len, " comments"

Notes

Broadcast Ids

You'll see you're supposed to pass a broadcastId in some API calls. When you receive events, you'll get this ID back, so you know to ignore the event if you plan to optimistically apply changes on the client (which you'll probably want to do since it offers the best experience). Pass a UUID here. The ID should be unique enough to not occur twice in a browser session.

SSO (Single Sign-On)

For SSO examples, see below.

SSO Usage

Simple SSO

import fastcomments/sso

let user = newSimpleSSOUserData(
  userId = "user-123",
  email = "user@example.com",
  avatar = "https://example.com/avatar.jpg"
)
let sso = newSimple(simpleUserData = user)
let token = sso.createToken()

echo "SSO Token: ", token

Secure SSO

import fastcomments/sso

let user = newSecureSSOUserData(
  userId = "user-123",
  email = "user@example.com",
  username = "johndoe",
  avatar = "https://example.com/avatar.jpg"
)

let apiKey = "your-api-key"
let sso = newSecure(apiKey = apiKey, secureUserData = user)
let token = sso.createToken()

echo "Secure SSO Token: ", token

Testing

Set the required environment variables:

export FASTCOMMENTS_API_KEY="your-api-key"
export FASTCOMMENTS_TENANT_ID="your-tenant-id"

Run the tests:

nimble test

Or run specific tests:

nim c -r tests/test_sso.nim
nim c -r tests/test_sso_integration.nim

Development

To update the generated client from the OpenAPI spec:

./update.sh

License

MIT License - see LICENSE file for details

Support

For support, please visit https://fastcomments.com/auth/my-account/help or email support@fastcomments.com