API | FastComments Docs

FastComments API

FastComments tilbyder et API til at interagere med mange ressourcer. Byg integrationer med vores platform, eller byg endda dine egne klienter!

I denne dokumentation finder du alle API'ens understøttede ressourcer dokumenteret med deres request- og response-typer.

For Enterprise-kunder registreres al API-adgang i Audit Log.

Genererede SDK'er

FastComments genererer nu en API Spec fra vores kode (dette er endnu ikke fuldt færdigt, men omfatter mange API'er).

Vi har også nu SDK'er til populære sprog:

Autentificering

API'en autentificeres ved at videregive din API-nøgle enten som en X-API-KEY header eller som forespørgselsparameteren API_KEY. Du får også brug for din tenantId for at foretage API-opkald. Den kan hentes fra samme side som din API-nøgle.

Sikkerhedsnote

Disse ruter er beregnet til at blive kaldt fra en server. KALD IKKE dem fra en browser. Hvis du gør det, vil din API-nøgle blive eksponeret - det vil give fuld adgang til din konto for enhver, der kan se kildeteksten på en side!

Autentificeringsmulighed Én - Headers

Header: X-API-KEY
Header: X-TENANT-ID

Autentificeringsmulighed To - Forespørgselsparametre

Forespørgselsparameter: API_KEY
Forespørgselsparameter: tenantId

API-ressourcer

FastComments API indeholder følgende ressourcer:

Comment
Domain Config
Page
Moderator
Notification
Vote
SSO User
Tenant User
User
QuestionConfig
QuestionResult
Subscription
Audit Log

Aggreger dine data

Resource: Aggregate as GET /api/v1/aggregate Credit Cost: 1

Dette API aggregerer dokumenter ved at gruppere dem (hvis groupBy er provided) og anvende flere operationer. Forskellige operationer (f.eks. sum, countDistinct, avg osv.) understøttes.

Omkostningen er variabel. Hver 500 scannede objekter koster 1 API-kredit.

Den maksimale hukommelsesbrug tilladt pr. API-kald er som standard 64MB, og som standard må du kun have én aggregation kørende ad gangen. Hvis du sender flere aggregationer samtidig, vil de blive sat i kø og kørt i den rækkefølge, de blev sendt. Ventende aggregationer vil vente maksimalt 60 sekunder; derefter vil anmodningen timeoute. Individuelle aggregationer kan køre i op til 5 minutter.

Hvis du har managed tenants, kan du aggregere alle child tenant resources i ét kald ved at angive query-parameteren parentTenantId.

Eksempler

Eksempel: Tæl unikke

cURL-eksempel: Antal unikke værdier

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "urlId", "alias": "urlId" },
        { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Svar: Antal unikke værdier

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": {
                "distinctCounts": {
                    "someone@somewhere.com": 1,
                    "someone2@somewhere.com": 1
                }
            }
        },
        {
            "urlId": {
                "distinctCounts": {
                    "some-page": 2
                }
            }
        }
    ],
    "stats": { "scanned": 2 }
}

Eksempel: Antal distinkte

cURL-eksempel: Antal distinkte værdier

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "countDistinct", "field": "urlId", "alias": "urlId" },
        { "op": "countDistinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Svar:

Svar: Antal distinkte værdier

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": { "distinctCount": 2 },
            "urlId": { "distinctCount": 1 }
        }
    ],
    "stats": { "scanned": 2 }
}

Eksempel: Sum af værdier for flere felter

cURL-eksempel: Sum af værdier

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "sum", "field": "votes", "alias": "votes" },
        { "op": "sum", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Svar:

Svar: Sum af værdier

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 2 },
            "votesUp": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 2 }
}

Eksempel: Gennemsnit af værdier for flere felter

cURL-eksempel: Gennemsnit af værdier

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "avg", "field": "votes", "alias": "votes" },
        { "op": "avg", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Svar:

Svar: Gennemsnit af værdier

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 1 },
            "votesUp": { "numericValue": 1 }
        }
    ],
    "stats": { "scanned": 2 }
}

Eksempel: Min/Max for flere felter

cURL-eksempel: Min/max-værdier

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "min", "field": "votes", "alias": "votes" },
        { "op": "min", "field": "votesUp", "alias": "votesUp" },
        { "op": "max", "field": "votes", "alias": "votes" },
        { "op": "max", "field": "votesUp", "alias": "votesUp" }
    ]
}'

Svar:

Svar: Min/max-værdier

Copy

{
    "status": "success",
    "data": [
        {
            "votes": { "numericValue": 0 },
            "votesUp": { "numericValue": 0 },
            "votes": { "numericValue": 2 },
            "votesUp": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 2 }
}

Eksempel: Tæl unikke værdier for flere felter

cURL-eksempel: Antal unikke værdier

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "urlId", "alias": "urlId" },
        { "op": "distinct", "field": "commenterEmail", "alias": "commenterEmail" }
    ]
}'

Svar:

Svar: Antal unikke værdier

Copy

{
    "status": "success",
    "data": [
        {
            "commenterEmail": {
                "distinctCounts": {
                    "someone@somewhere.com": 1,
                    "someone2@somewhere.com": 1
                }
            },
            "urlId": {
                "distinctCounts": {
                    "some-page": 2
                }
            }
        }
    ],
    "stats": { "scanned": 2 }
}

Eksempel: Oprettelse af forespørgsel

cURL-eksempel: Oprettelse af forespørgsel

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "groupBy": ["commenterName"],
    "query": [
        { "key": "approved", "value": true, "operator": "eq" },
        { "key": "commenterName", "value": "some-username-2", "operator": "eq" }
    ],
    "operations": [
        { "op": "sum", "field": "votes", "alias": "votes" }
    ]
}'

Svar:

Svar: Oprettelse af forespørgsel

Copy

{
    "status": "success",
    "data": [
        {
            "groups": { "commenterName": "some-username-2" },
            "votes": { "numericValue": 2 }
        }
    ],
    "stats": { "scanned": 1 }
}

Eksempel: Tæl kommentarer, der venter på gennemgang

cURL-eksempel: Tæl kommentarer, der venter på gennemgang

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "query": [
        { "key": "reviewed", "value": true, "operator": "not_eq" }
    ],
    "operations": [
        { "op": "count", "field": "id", "alias": "count" }
    ]
}'

Svar:

Svar: Tæl kommentarer, der venter på gennemgang

Copy

{
    "status": "success",
    "data": [
        { "count": { "numericValue": 2 } }
    ],
    "stats": { "scanned": 2 }
}

Eksempel: Opdeling af godkendte, gennemgåede og spam-kommentarer

cURL-eksempel: Opdeling af kommentarer

Copy

curl --request POST --url 'https://fastcomments.com/api/v1/aggregate?tenantId=demo&API_KEY=DEMO_API_SECRET&includeStats=true' --header 'Content-Type: application/json' --data '{
    "resourceName": "Comment",
    "operations": [
        { "op": "distinct", "field": "approved", "alias": "approved" },
        { "op": "distinct", "field": "reviewed", "alias": "reviewed" },
        { "op": "distinct", "field": "isSpam", "alias": "isSpam" }
    ]
}'

Svar:

Svar: Opdeling af kommentarer

Copy

{
    "status": "success",
    "data": [
        {
            "approved": { "distinctCounts": { "true": 2 } },
            "reviewed": { "distinctCounts": { "false": 2 } },
            "isSpam": { "distinctCounts": { "false": 2 } }
        }
    ],
    "stats": { "scanned": 2 }
}

Strukturer

Struktur for aggregationsanmodning

Copy

export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
/** En operation, der vil blive anvendt på et felt */
export interface AggregationOperation {
    /** Feltet, der skal opereres på */
    field: string;
    /** Typen af operation */
    op: AggregationOpType;
    /** Valgfrit alias for output; hvis ikke angivet, beregnes et standardalias */
    alias?: string;
    expandArray?: boolean;
}
export interface QueryPredicate {
    key: string
    value: string | number | boolean
    operator: 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'contains'
}
export interface AggregationRequest {
    query?: QueryPredicate[];
    resourceName: string;
    groupBy?: string[];
    operations: AggregationOperation[];
    sort?: {
        field: string;
        dir: 'asc' | 'desc';
    };
}
type DistinctAccumulator = Record<string, number>;
type GroupValues = Record<string, string>;
export type AggregationValue = {
    distinctCounts?: DistinctAccumulator
    distinctCount?: number
    numericValue?: number
    stringValue?: string
    groups?: GroupValues
};

Struktur for aggregationssvar

Copy

export type AggregationItem = Record<string, AggregationValue> & { groups?: GroupValues };
export interface AggregationResponse {
    status: APIStatus,
    data: AggregationItem[];
    stats?: {
        scanned: number;
        timeMS: number;
    };
}

Følgende ressourcer kan aggregeres:

AffiliateEvent
AnonymousVote
BannedUser
BatchJob
BlockedUser
Comment
CommentDeleted
CommentIdToSyncOutbound
CommentScheduled
CommentSyncLog
CustomConfig
CustomEmailTemplateRenderError
EmailToSend
EventLogEntry
ImportedCommentScheduled
ModerationGroup
Moderator
Page
PageReact
PendingVote
QuestionResult
SSOUser
SentEmail
SpamEvent
Tenant
TenantAuditLog
TenantBadge
TenantDailyUsage
TenantInvoiceHistory
TenantPackage
User
UserBadge
UserBadgeProgress
UserNotification
UserSubscription
UserUsage
Vote

Auditlog-struktur

Et AuditLog er et objekt, der repræsenterer en revideret hændelse for lejere, der har adgang til denne funktion.

Strukturen for AuditLog-objektet er som følger:

AuditLog-struktur

Copy

interface AuditLog {
    id: string;
    userId?: string;
    username?: string;
    resourceName: string;
    crudType: 'c' | 'r' | 'u' | 'd' | 'login';
    from: string;
    url?: string;
    ip?: string;
    when: string;
    description?: string;
    serverStartDate: string;
    objectDetails?: object;
}

Auditloggen er uforanderlig. Den kan heller ikke skrives til manuelt. FastComments.com beslutter alene, hvornår der skrives til auditloggen. Du kan dog læse fra den via dette API.

Hændelser i auditloggen udløber efter to år.

GET /api/v1/audit-logs

Resource: AuditLog as GET /api/v1/audit-logs Credit Cost: 1

Denne rute returnerer audit logs i sider af 100. Paginering leveres af skip-parameteren. Audit logs er sorteret efter createdAt og id.

AuditLog cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/audit-logs?tenantId=demo&API_KEY=DEMO_API_SECRET'

AuditLog Anmodningsstruktur

Copy

interface AuditLogsRequestQueryParams {
    tenantId: string
    API_KEY: string
    skip?: number
    /** Filter by creator (user id). **/
    createdBy?: string
    /** A start date to filter. Inclusive. Should be JSON (ex 2021-01-01T00:00:00.000Z) **/
    startDate?: string
    /** An end date to filter. Exclusive. Should be JSON (ex 2021-01-01T00:00:00.000Z) **/
    endDate?: string
}

AuditLog Svarstruktur

Copy

interface AuditLogsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    auditLogs: AuditLog[]
}

Kommentarstruktur

Et Comment-objekt repræsenterer en kommentar efterladt af en bruger.

Forholdet mellem forældre- og underkommentarer defineres via parentId.

Strukturen for Comment-objektet er som følger:

Kommentarstruktur

Copy

interface Comment {
    /** READONLY: Set to true if the spam engine determined the comment was spam. **/
    aiDeterminedSpam?: boolean
    /** Whether the comment is approved to show. Set to true when saving the comment, else it will be hidden. **/
    approved?: boolean
    /** The user's avatar. **/
    avatarSrc?: string
    /** Child comments. Not populated in all scenarios. Used when asTree is set to true via the API. **/
    children: Comment[]
    /** The commenter's raw comment. **/
    comment: string
    /** READONLY: The commenter's comment parsed into HTML. **/
    commentHTML?: string
    /** The commenter's email. Required if anonymous commenting is off. **/
    commenterEmail?: string
    /** The commenter's link (for example, their blog). **/
    commenterLink?: string
    /** The commenter's name. Always required. If not available, set to something like "Anonymous". **/
    commenterName: string
    /** The date the comment was left, in UTC epoch. **/
    date: number
    /** The "display label" for the comment - for example "Admin", "Moderator", or something like "VIP User". **/
    displayLabel?: string
    /** The domain the comment was posted on. **/
    domain?: string
    /** READONLY: The number of times the comment was flagged. **/
    flagCount?: number
    /** The #hashtags written in the comment that were successfully parsed. You can also manually add hashtags, for querying, but they won't display in the comment text automatically. **/
    hashTags?: CommentHashTag[]
    /** READONLY: Does the comment contain images? **/
    hasImages?: boolean
    /** READONLY: Does the comment contain links? **/
    hasLinks?: boolean
    /** READONLY: The unique comment id. **/
    id: string
    /** Only on create! This is hashed for storage. **/
    ip?: string
    /** READONLY: Did the current user block the user that wrote this comment? **/
    isBlocked?: boolean
    /** READONLY: Is the comment by an admin? Automatically set based on userId. **/
    isByAdmin?: boolean
    /** READONLY: Is the comment by a moderator? Automatically set based on userId. **/
    isByModerator?: boolean
    /** Set to true if the comment was soft deleted (placeholder had to be left due to some other configuration). **/
    isDeleted?: boolean
    /** Set to true if the user's account was deleted and the comment had to be retained. **/
    isDeletedUser?: boolean
    /** READONLY: Is the flagged by the currently logged-in user (contextUserId)? **/
    isFlagged?: boolean
    /** Is the comment pinned? **/
    isPinned?: boolean
    /** Is the comment locked for new replies (moderators still can reply)? **/
    isLocked?: boolean
    /** Is the comment spam? **/
    isSpam?: boolean
    /** READONLY: Is the comment voted down for the current user (contextUserId)? **/
    isVotedDown?: boolean
    /** READONLY: Is the comment voted up for the current user (contextUserId)? **/
    isVotedUp?: boolean
    /** The locale the comment is in. If not provided, will be derived from the language accept HTTP header. **/
    locale?: 'de_de' | 'en_us' | 'es_es' | 'fr_fr' | 'it_it' | 'ja_jp' | 'ko_kr' | 'pl_pl' | 'pt_br' | 'ru_ru' | 'tr_tr' | 'zh_cn' | 'zh_tw'
    /** READONLY: The @mentions written in the comment that were successfully parsed. **/
    mentions?: CommentUserMention[]
    /** Optional metadata associated with the comment. **/
    meta?: Record<string, string | number | boolean>
    /** The optional list of moderation group ids associated with this comment. **/
    moderationGroupIds?: string[]|null
    /** READONLY: The id of the vote object that corresponds to the vote from the current user (contextUserId) on this comment. **/
    myVoteId?: string
    /** Whether notifications were sent for this comment for commenters. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParent?: boolean
    /** Whether notifications were sent for this comment for tenant users. To prevent notifications being sent on imports, set this to true. **/
    notificationSentForParentTenant?: boolean
    /** The title of the page this comment was on. **/
    pageTitle?: string
    /** If we're replying to a comment, this is the ID that we are replying to. **/
    parentId?: string|null
    /** Whether the comment is marked reviewed. **/
    reviewed: boolean
    /** The tenant id where the comment belongs. **/
    tenantId: string
    /** The user that wrote the comment. Created automatically when saving a comment with a name/email. **/
    userId?: string|null
    /** The URL to the location that this comment is visible, like a blog post. **/
    url: string
    /** A "cleaned" version of the urlId you passed us. When saving, you specify this field, but when you fetch the comment back this will be "cleaned" and your original value moved to "urlIdRaw". **/
    urlId: string
    /** READONLY: The original urlId you passed us. **/
    urlIdRaw?: string
    /** Is the user and this comment verified? **/
    verified: boolean
    /** Number of votes up. **/
    votesUp?: number
    /** Number of votes down. **/
    votesDown?: number
    /** The "karma" of the comment (= votes up - votes down). **/
    votes?: number
}

Some of these fields are marked READONLY - these are returned by the API but cannot be set.

Comment Text Structure

Comments are written in a FastComments flavor of markdown, which is just markdown plus traditional bbcode style tags for images, like [img]path[/img].

Text is stored in two fields. The text the user entered is stored unmodified in the comment field. This is rendered and stored in the commentHTML field.

The allowed HTML tags are b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, and br.

It's recommended to render the HTML, since it is a very small subset of HTML, building a renderer is pretty straightforward. There are multiple libraries for React Native and Flutter, for instance, to help with this

You may choose to render the un-normalized value of the comment field. An example parser is here..

The example parser could also be adjusted to work with HTML, and transform the HTML tags into expected elements to render for your platform.

Tagging

When users are tagged in a comment, the information is stored in a list called mentions. Each object in that list has the following structure.

Objektet for kommentaromtaler

Copy

Run

interface CommentUserMention {
    /** The user id. For SSO users, this will have your tenant id prefixed. **/
    id: string
    /** The final @mention tag text, including the @ symbol. **/
    tag: string
    /** The original @mention tag text, including the @ symbol. **/
    rawTag: string
    /** What type of user was tagged. user = FastComments.com account. sso = SSOUser. **/
    type: 'user'|'sso'
    /** If the user opts out of notifications, this will still be set to true. **/
    sent: boolean
}

HashTags

When hashtags are used and successfully parsed, the information is stored in a list called hashTags. Each object in that list has the following structure. Hashtags can also be manually added to the comment hashTags array for querying, if retain is set.

Objektet for kommentar-hashtags

Copy

Run

interface CommentHashTag {
    /** The hashtag id. **/
    id: string
    /** The final #hashtag tag text, including the # symbol. **/
    tag: string
    /** If the hashtag is associated with a custom URL, this will be defined. **/
    url?: string
    /** If we should retain the hashtag, even if it does not exist in the comment text, when the comment is updated. Useful for tagging comments without changing comment text. **/
    retain?: boolean
}

GET /api/v1/comments

Resource: Comment as GET /api/v1/comments Credit Cost: 1

Dette API bruges til at hente kommentarer til visning for en bruger. For eksempel filtrerer det automatisk ikke-godkendte eller spam-kommentarer.

Paginering

Paginering kan gøres på en af to måder, afhængigt af performance-krav og brugssag:

Hurtigst: Forudberegnet paginering:
1. Dette er hvordan FastComments fungerer, når du bruger vores forbyggede widgets og klienter.
2. At klikke "næste" øger simpelthen side-tælleren.
3. Du kan tænke på dette som hentet fra en key-value store.
4. På denne måde definerer du blot en page parameter startende ved 0 og en sorteringsretning som direction.
5. Sidestørrelser kan tilpasses via tilpasningsregler.
Mest fleksibel: Fleksibel paginering:
1. På denne måde kan du definere brugerdefinerede limit og skip parametre. Send ikke page.
2. Sorterings-direction understøttes også.
3. limit er det samlede antal der returneres efter skip er anvendt.
  - Eksempel: sæt skip = 200, limit = 100 når page size = 100 og page = 2.
4. Underkommentarer tæller stadig med i pagineringen. Du kan komme uden om dette ved at bruge asTree-muligheden.
  - Du kan paginere børn via limitChildren og skipChildren.
  - Du kan begrænse dybden af de tråde der returneres via maxTreeDepth.

Tråde

Når du bruger Precalculated Pagination, er kommentarer grupperet efter side og kommentarer i tråde påvirker den overordnede side.
1. På denne måde kan tråde bestemmes på klienten baseret på parentId.
2. For eksempel, med en side med én topniveau-kommentar og 29 svar, og sætning af page=0 i API'et - vil du kun få topniveau-kommentaren og de 29 børn.
3. Eksempelbillede der illustrerer flere sider.
Når du bruger Flexible Pagination, kan du definere en parentId parameter.
1. Sæt denne til null for kun at få topniveau-kommentarer.
2. For så at se tråde, kald API'et igen og giv parentId.
3. En almindelig løsning er at lave et API-kald for topniveau-kommentarerne og derefter lave parallelle API-kald for at hente kommentarer for børnene af hver kommentar.
NYT fra feb 2023! Hent som et træ ved at bruge &asTree=true.
1. Du kan tænke på dette som Flexible Pagination as a Tree.
2. Kun topniveau-kommentarer tæller i pagineringen.
3. Sæt parentId=null for at starte træet ved roden (du skal sætte parentId).
4. Sæt skip og limit for paginering.
5. Sæt asTree til true.
6. Kreditforbruget øges med 2x, da vores backend skal lave meget mere arbejde i dette scenarie.
7. Sæt maxTreeDepth, limitChildren, og skipChildren som ønsket.

Træer forklaret

Når du bruger asTree, kan det være svært at sætte sig ind i paginering. Her er en nyttig grafik:

Diagram over paginering i træ

Hentning af kommentarer i brugerkontekst

/comments API'et kan bruges i to kontekster, til forskellige brugssager:

Til at returnere kommentarer sorteret og tagget med information til at bygge din egen klient.
- I dette tilfælde definer en contextUserId forespørgselsparameter.
Til at hente kommentarer fra din backend til brugerdefinerede integrationer.
- Platformen vil som standard bruge dette uden contextUserId.

Kommentarer Forudberegnet Paginering

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&page=0&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR'

Kommentarer Fleksibel Paginering

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10'

Kommentarer Fleksibel Paginering i Brugerkontekst

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id'

Kommentarer Fleksibel Paginering i Brugerkontekst kun for Topniveau-kommentarer

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null'

Hent kommentarer som et træ

Det er muligt at få kommentarerne returneret som et træ, hvor paginering kun tæller topniveau-kommentarerne.

Kommentarer som træ i Brugerkontekst

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true'

Vil du kun hente topniveau-kommentarerne og de umiddelbare børn? Her er én måde:

Kommentarer som træ med Maksimal Dybde

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&urlId=test&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&maxTreeDepth=1&limitChildren=10'

Dog kan du i din UI få brug for at vide, om du skal vise en "show replies"-knap på hver kommentar. Når du henter kommentarer via et træ, er der en hasChildren property knyttet til kommentarer, når det er relevant.

Hent kommentarer som træ, søgning efter hashtag

Det er muligt at søge efter hashtag ved hjælp af API'et, på tværs af hele din tenant (ikke begrænset til en side eller urlId).

I dette eksempel udelader vi urlId, og vi søger efter flere hashtags. API'et vil kun returnere kommentarer, der har alle de forespurgte hashtags.

Kommentarer som træ i Brugerkontekst, efter Hashtag

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&direction=MR&skip=20&limit=10&contextUserId=my-user-id&parentId=null&asTree=true&hashTag=TestTag&hashTag=OtherTestTag'

Alle forespørgselsparametre

Kommentarer Forespørgselsstruktur

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The urlId (page url, or article id) the comments are associated with. **/
    urlId?: string
    /** Limit the comments returned by this user. **/
    userId?: string
    /** Use this to search by hashtag. To drill down to the intersection of multiple hashtags, do &hashTag=a&hashTag=b. **/
    hashTag?: string
    /** The sort direction. Default is MR (Most Relevant). Other options are OF (Oldest First) and NF (Newest First). **/
    direction?: 'MR' | 'OF' | 'NF'
    /** Precalculated Pagination: The page to fetch, starting with 0. Pass -1 for all comments (up to 250). **/
    page?: number
    /** Flexible Pagination: How many comments should we return? **/
    limit?: number
    /** Flexible Pagination: How many child comments should we return for each parent? **/
    limitChildren?: number
    /** Flexible Pagination: How many comments should we skip? **/
    skip?: number
    /** Flexible Pagination: How many child comments should we skip for each parent? **/
    skipChildren?: number
    /** For determining blocked and flagged comments. **/
    contextUserId?: string
    /** For determining blocked and flagged comments. **/
    anonUserId?: string
    /** For fetching child comments. **/
    parentId?: string
    /** For fetching as a tree. **/
    asTree?: boolean
    /** How far into the tree should we return data? 0 returns no children. 1 returns immediate children, etc. **/
    maxTreeDepth?: number
}

Svaret

Kommentarer Svarstruktur

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-date' | 'unauthorized-page' | 'invalid-pagination-request' | 'invalid-limit' | 'invalid-limit-children' | 'invalid-skip' | 'invalid-skip-children' | 'invalid-max-tree-depth'
    /** Included on failure. **/
    reason?: string
    /** The comments! **/
    comments: Comment[]
}

Brugbare tips

URL-id

Du vil sandsynligvis bruge Comment API'et med urlId parameteren. Du kan kalde Pages API'et først for at se, hvordan de urlId værdier der er tilgængelige for dig ser ud.

Anonyme handlinger

For anonym kommentering vil du sandsynligvis sende anonUserId når du henter kommentarer, og når du foretager flagging og blokering.

(!) Dette er påkrævet for mange app-butikker, da brugere skal kunne markere brugeroprettet indhold, de kan se, selvom de ikke er logget ind. Hvis ikke, kan din app blive fjernet fra den pågældende butik.

Kommentarer returneres ikke

Kontroller at dine kommentarer er godkendte, og ikke er spam.

GET /api/v1/comments/:id

Resource: Comment as GET /api/v1/comments/:id Credit Cost: 1

Denne API giver mulighed for at hente en enkelt kommentar efter id.

Comments Get-By-Id cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/comments/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Comment Get-By-Id Anmodningsstruktur

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Comments Get-By-Id Svarstruktur

Copy

interface CommentGetByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'
    /** Included on failure. **/
    reason?: string
    /** The comment! **/
    comment?: Comment
}

POST /api/v1/comments

Resource: Comment as POST /api/v1/comments Credit Cost: 1

Dette API-endpoint giver mulighed for at oprette kommentarer.

Almindelige anvendelsestilfælde er brugerdefinerede UI'er, integrationer eller imports.

Bemærkninger:

Dette API kan opdatere kommentarwidgeten "live", hvis ønsket (dette øger creditsCost fra 1 til 2).
Dette API vil automatisk oprette brugerobjekter i vores system, hvis der angives en e-mail.
Forsøg på at gemme to kommentarer med forskellige e-mails, men samme brugernavn, vil resultere i en fejl for den anden kommentar.
Hvis du angiver parentId, og en børnekommentar har notificationSentForParent sat til false, vil vi sende notifikationer for forældrekommentaren. Dette gøres hver time (vi samler notifikationerne for at reducere antallet af sendte e-mails).
Hvis du vil sende velkomst-e-mails ved oprettelse af brugere, eller e-mails til verifikation af kommentarer, sæt sendEmails til true i forespørgselsparametrene.
Kommentarer oprettet via dette API vil blive vist på Analytics- og Moderation-siderne i admin-appen.
"bad words" bliver stadig maskerede i kommentatornavne og kommentartekst, hvis indstillingen er slået til.
Kommentarer oprettet via dette API kan stadig blive tjekket for spam, hvis ønsket.
Konfiguration såsom maksimal kommentar-længde, hvis konfigureret via Customization Rule-adminsiden, vil gælde her.

De minimale data, der kræves for at indsende og som vil blive vist i kommentar-widgeten, er følgende:

Minimum Kommentar POST cURL-eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "approved": true,
    "comment": "some-comment",
    "commenterName": "some-commenter-name",
    "date": 1622644382148,
    "urlId": "some-place",
    "url": "https://exmaple.com/some-page",
    "verified": true
}'

En mere realistisk forespørgsel kan se sådan ud:

Kommentar POST cURL-eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true&doSpamCheck=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "approved": true,
    "avatarSrc": "https://static.fastcomments.com/1605337537848-DSC_0841.JPG",
    "comment": "some-comment",
    "commenterName": "some-commenter-name",
    "commenterEmail": "fordperfect@spaceship.com",
    "date": 1622644382148,
    "isSpam": false,
    "locale": "en_us",
    "notificationSentForParent": true,
    "notificationSentForParentTenant": true,
    "reviewed": true,
    "urlId": "some-place",
    "url": "https://exmaple.com/some-page",
    "verified": true,
    "votes": 1,
    "votesUp": 2,
    "votesDown": 1,
    "ip": "123.456.789.000"
}'

Kommentar POST-forespørgselsstruktur

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** Om kommentaren skal vises "live" for brugere, der ser instanser af kommentarwidgeten med samme urlId. BEMÆRK: Fordobler kreditforbruget fra 1 til 2. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

Kommentar POST-responsstruktur

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** Medtages ved fejl. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email';
    /** Medtages ved fejl. **/
    reason?: string
    /** Den oprettede kommentar. **/
    comment?: Comment
    /** Den tilknyttede bruger, som måske allerede fandtes eller ej. **/
    user?: User
}

PATCH /api/v1/comments/:id

Resource: Comment as PATCH /api/v1/comments/:id Credit Cost: 1

Denne API-endpoint giver mulighed for at opdatere en enkelt kommentar.

Bemærkninger:

Denne API kan opdatere kommentar-widget'en "live" hvis ønsket (dette øger basis-creditsCost fra 1 til 2).
- Dette kan gøre migrering af kommentarer mellem sider "live" (ændring af urlId).
- Migreringer koster yderligere 2 kreditter, da sider er forudberegnet, og dette er CPU-intensivt.
I modsætning til oprettelses-API'et vil denne API IKKE automatisk oprette brugerobjekter i vores system, hvis e-mail er angivet.
Kommentarer opdateret via denne API kan stadig kontrolleres for spam, hvis ønsket.
Konfiguration såsom maksimal kommentarlængde, hvis konfigureret via Tilpasningsregel-administrationssiden, vil gælde her.
For at tillade brugere at opdatere deres kommentartekst, kan du bare angive comment i anmodningskroppen. Vi vil generere den resulterende commentHTML.
- Hvis du definerer både comment og commentHTML, vil vi ikke automatisk generere HTML'en.
- Hvis brugeren tilføjer omtaler eller hashtags i deres nye tekst, vil det stadig blive behandlet som POST API'et.
Når du opdaterer commenterEmail på en kommentar, er det bedst også at angive userId. Ellers skal du sikre, at brugeren med denne e-mail tilhører din tenant, ellers vil anmodningen fejle.

Minimum Comment PATCH cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET&isLive=true' \
  --header 'Content-Type: application/json' \
  --data '{
    "comment": "some-new-comment-text"
}'

Comment PATCH Anmodningsstruktur

Copy

interface CommentPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** The user doing the update. If desired can be used to check that they can edit the comment.  **/
    contextUserId?: string
    /** Should we check if the new comment looks like spam?  **/
    doSpamCheck?: 'true' | 'false'
    /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
}

Comment PATCH Svarstruktur

Copy

interface CommentPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email' | 'invalid-input' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/comments/:id

Resource: Comment as DELETE /api/v1/comments/:comment-id Credit Cost: 1

Denne rute giver mulighed for at fjerne en enkelt kommentar.

Comment Sletning cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Comment Sletning Anmodningsstruktur

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** The comment id to delete. Note this is in the path, not query params. **/
    commentId: string
}

Comment Sletning Svarstruktur

Copy

interface CommentDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/comments/:id/flag

Resource: Comment as POST /api/v1/comments/:id/flag Credit Cost: 1

Denne API-endpoint giver mulighed for at rapportere en kommentar for en specifik bruger.

Bemærkninger:

Dette kald skal altid foretages i konteksten af en bruger. Brugeren kan være en FastComments.com-bruger, SSO-bruger eller Tenant-bruger.
Hvis en flag-til-skjul-tærskel er sat, vil kommentaren automatisk blive skjult live, efter den er blevet rapporteret det definerede antal gange.
Efter den automatisk er blevet fjernet fra godkendelse (skjult) - kan kommentaren kun gen-godkendes af en administrator eller moderator. Fjernelse af rapportering vil ikke gen-godkende kommentaren.

Comment Flag cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

For anonym rapportering skal vi angive en anonUserId. Dette kan være et ID, der repræsenterer den anonyme session, eller et tilfældigt UUID. Dette giver os mulighed for at understøtte rapportering og fjernelse af rapportering af kommentarer, selvom en bruger ikke er logget ind. På denne måde kan kommentaren markeres som rapporteret, når kommentarer hentes med det samme anonUserId.

Anonymous Comment Flag cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Comment Flag Anmodningsstruktur

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
}

Comment Flag Svarstruktur

Copy

interface CommentFlagResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Included on failure. **/
    reason?: string
    /** Was the comment un-approved (hidden) due to being flagged too many times? **/
    wasUnapproved?: boolean;
}

POST /api/v1/comments/:id/un-flag

Resource: Comment as POST /api/v1/comments/:id/un-flag Credit Cost: 1

Denne API-endpoint giver mulighed for at fjerne rapportering af en kommentar for en specifik bruger.

Bemærkninger:

Dette kald skal altid foretages i konteksten af en bruger. Brugeren kan være en FastComments.com-bruger, SSO-bruger eller Tenant-bruger.
Efter en kommentar automatisk er blevet fjernet fra godkendelse (skjult) - kan kommentaren kun gen-godkendes af en administrator eller moderator. Fjernelse af rapportering vil ikke gen-godkende kommentaren.

Comment Un-Flag cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

For anonym rapportering skal vi angive en anonUserId. Dette kan være et ID, der repræsenterer den anonyme session, eller et tilfældigt UUID.

Anonymous Comment Flag cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-flag?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Comment Un-Flag Anmodningsstruktur

Copy

interface CommentFlagQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
}

Comment Un-Flag Svarstruktur

Copy

interface CommentUnFlagResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/comments/:id/block

Resource: Comment as POST /api/v1/comments/:id/block Credit Cost: 1

Denne API-endpoint giver mulighed for at blokere en bruger, der har skrevet en given kommentar. Det understøtter blokering fra kommentarer skrevet af FastComments.com-brugere, SSO-brugere og Tenant-brugere.

Det understøtter en commentIdsToCheck body-parameter til at kontrollere, om andre potentielt synlige kommentarer på klienten skal blokeres/afblokeres efter denne handling udføres.

Bemærkninger:

Dette kald skal altid foretages i konteksten af en bruger. Brugeren kan være en FastComments.com-bruger, SSO-bruger eller Tenant-bruger.
userId i anmodningen er brugeren, der udfører blokeringen. For eksempel: Bruger A vil blokere Bruger B. Angiv userId=Bruger A og kommentar-id'et som Bruger B skrev.
Fuldstændig anonyme kommentarer (ingen bruger-id, ingen e-mail) kan ikke blokeres, og en fejl vil blive returneret.

Comment Block cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

For anonym blokering skal vi angive en anonUserId. Dette kan være et ID, der repræsenterer den anonyme session, eller et tilfældigt UUID. Dette giver os mulighed for at understøtte blokering af kommentarer, selvom en bruger ikke er logget ind, ved at hente kommentarerne med det samme anonUserId.

Anonymous Comment Block cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Comment Block Anmodningsstruktur

Copy

interface CommentBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentIdsToCheck?: string[]
}

Comment Block Svarstruktur

Copy

interface CommentBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
    /** Included on failure. **/
    reason?: string
    /** If commentIdsToCheck is defined, entries in this map with true are also blocked. **/
    commentStatuses?: Record<string, boolean>;
}

POST /api/v1/comments/:id/un-block

Resource: Comment as POST /api/v1/comments/:id/un-block Credit Cost: 1

Denne API-endpoint giver mulighed for at afblokere en bruger, der har skrevet en given kommentar. Det understøtter afblokering fra kommentarer skrevet af FastComments.com-brugere, SSO-brugere og Tenant-brugere.

Det understøtter en commentIdsToCheck body-parameter til at kontrollere, om andre potentielt synlige kommentarer på klienten skal blokeres/afblokeres efter denne handling udføres.

Bemærkninger:

Dette kald skal altid foretages i konteksten af en bruger. Brugeren kan være en FastComments.com-bruger, SSO-bruger eller Tenant-bruger.
userId i anmodningen er brugeren, der udfører afblokeringen. For eksempel: Bruger A vil afblokere Bruger B. Angiv userId=Bruger A og kommentar-id'et som Bruger B skrev.
Fuldstændig anonyme kommentarer (ingen bruger-id, ingen e-mail) kan ikke blokeres, og en fejl vil blive returneret.

Comment Un-Block cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=some-user-id' \
  --header 'Content-Type: application/json'

Anonymous Comment Un-Block cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/comments/some-comment-id/un-block?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-anon-user-id' \
  --header 'Content-Type: application/json'

Comment Un-Block Anmodningsstruktur

Copy

interface CommentUnBlockQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentIdsToCheck?: string[]
}

Comment Un-Block Svarstruktur

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id' | 'comment-cannot-be-blocked'
    /** Included on failure. **/
    reason?: string
    /** If commentIdsToCheck is defined, entries in this map with true are still blocked. If false, you might want to un-hide the comments from the user so they don't have to refresh. **/
    commentStatuses?: Record<string, boolean>;
}

E-mail-skabelonstruktur

Et EmailTemplate-objekt repræsenterer konfiguration for en tilpasset e-mail-skabelon, for en tenant.

Systemet vil vælge e-mail-skabelonen, der skal bruges via:

Dens typeidentifikator, vi kalder denne emailTemplateId. Disse er konstanter.
domain. Vi vil først forsøge at finde en skabelon for domænet, som det relaterede objekt (såsom en Comment) er knyttet til, og hvis et match ikke findes, vil vi forsøge at finde en skabelon, hvor domain er null eller *.

Strukturen for EmailTemplate-objektet er som følger:

Email Template Struktur

Copy

interface EmailTemplate {
    id: string
    tenantId: string
    emailTemplateId: string
    displayName: string
    /** READONLY **/
    createdAt: string
    /** READONLY **/
    updatedAt: string
    /** READONLY **/
    updatedByUserId: string
    /** The domain the template should be associated with. **/
    domain?: string | '*' | null
    /** The email template content in EJS syntax. **/
    ejs: string
    /** A map of overridden translation keys to values, for each supported locale. **/
    translationOverridesByLocale: Record<string, Record<string, string>>
    /** An object that represents the render context of the template. **/
    testData: object
}

Bemærkninger

Du kan få de gyldige emailTemplateId-værdier fra /definitions-endpointet.
/definitions-endpointet inkluderer også standardoversættelserne og testdata.
Skabeloner vil fejle ved gemning med ugyldig struktur eller testdata.

GET /api/v1/email-templates/:id

Resource: EmailTemplate as GET /api/v1/email-templates/:id Credit Cost: 1

Individuelle EmailTemplates kan hentes via deres tilsvarende id (IKKE emailTemplateId).

EmailTemplate efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

EmailTemplate efter ID Anmodningsstruktur

Copy

interface EmailTemplatesByIdRequestQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate efter ID Svarstruktur

Copy

interface EmailTemplateResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Included on failure. **/
    reason?: string
    emailTemplate?: EmailTemplate | null
}

GET /api/v1/email-templates

Resource: EmailTemplate as GET /api/v1/email-templates Credit Cost: 1

Denne API bruger paginering, leveret af page query-parameteren. EmailTemplates returneres i sider af 100, sorteret efter createdAt og derefter id.

EmailTemplate cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

EmailTemplate Anmodningsstruktur

Copy

interface EmailTemplatesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The page to fetch, starting with 0. **/
    page: number
}

EmailTemplate Svarstruktur

Copy

interface EmailTemplatesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    emailTemplates: EmailTemplate[]
}

PATCH /api/v1/email-templates/:id

Resource: EmailTemplate as PATCH /api/v1/email-templates/:id Credit Cost: 1

Denne API-endpoint giver mulighed for at opdatere en e-mail-skabelon ved kun at angive id'et og attributterne, der skal opdateres.

Bemærk at alle de samme valideringer for oprettelse af en skabelon også gælder, for eksempel:

Skabelonen skal kunne renderes. Dette kontrolleres ved hver opdatering.
Du kan ikke have duplikerede skabeloner for det samme domæne (ellers ville en blive ignoreret lydløst).

EmailTemplate PATCH cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "Some New Name",
}'

EmailTemplate PATCH Anmodningsstruktur

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate PATCH Svarstruktur

Copy

interface EmailTemplatePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'not-found' | 'unexpected-param' | 'invalid-email-template-id' | 'unauthorized' | 'domain-invalid' | 'duplicate' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The updated email template. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates

Resource: EmailTemplate as POST /api/v1/email-templates Credit Cost: 1

Denne API-endpoint giver mulighed for at oprette e-mail-skabeloner.

Bemærkninger:

Du kan ikke have flere skabeloner med det samme emailTemplateId med det samme domæne.
Men du kan have en wildcard-skabelon (domain = * og en domænespecifik skabelon for det samme emailTemplateId).
Angivelse af domain er kun relevant, hvis du har forskellige domæner, eller ønsker at bruge specifikke skabeloner til test (domain sat til localhost osv.).
Hvis du angiver domain, skal det matche en DomainConfig. Ved fejl gives en liste over gyldige domæner.
Skabelonsyntaksen er EJS og renderes med en timeout på 500ms. P99 for rendering er <5ms, så hvis du rammer 500ms, er der noget galt.
Din skabelon skal kunne renderes med dine givne testData for at gemme. Renderingsfejl aggregeres og rapporteres i dashboardet (snart tilgængeligt via API).

De minimale data, der kræves for at tilføje en skabelon, er som følger:

Minimum EmailTemplate POST cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
}'

Du vil måske have skabeloner per-site, i hvilket tilfælde du definerer domain:

EmailTemplate POST cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is some email content!",
    "domain": "somespecificsite.com",
}'

EmailTemplate POST Anmodningsstruktur

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST Svarstruktur

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'invalid-email-template-id' | 'domain-invalid' | 'duplicate' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The created template. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates/render

Resource: EmailTemplate as POST /api/v1/email-templates/render Credit Cost: 1

Denne API-endpoint giver mulighed for at forhåndsvise e-mail-skabeloner.

Minimum EmailTemplate Forhåndsvisning POST cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/email-templates/render?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailTemplateId": "comment-user-mention",
    "displayName": "I'm a custom template.",
    "ejs": "This is an @mention notification! My name is <%= comment.commenterName %>."
}'

EmailTemplate POST Anmodningsstruktur

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST Svarstruktur

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
    /** Included on failure. **/
    reason?: string
    /** The rendered HTML on success. **/
    html?: string
}

DELETE /api/v1/email-templates/:id

Resource: EmailTemplate as DELETE /api/v1/email-templates/:id Credit Cost: 1

Denne rute giver mulighed for at fjerne en enkelt EmailTemplate efter id.

EmailTemplate Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/email-templates/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

EmailTemplate Fjernelse Anmodningsstruktur

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate Fjernelse Svarstruktur

Copy

interface EmailTemplateDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
}

Hashtag-struktur

Et HashTag-objekt repræsenterer et tag, der kan efterlades af en bruger. HashTags kan bruges til at linke til eksternt indhold eller til at knytte relaterede kommentarer sammen.

Strukturen for HashTag-objektet er som følger:

HashTag Struktur

Copy

interface HashTag {
    /** Should start with the "#" or desired character. **/
    tag: string
    /** An optional URL that the hashtag can point to. Instead of filtering comments by hashtag, the UI will redirect to this upon click. **/
    url?: string
    /** READONLY **/
    createdAt: string
}

Bemærkninger:

I nogle API-endpoints vil du se, at hashtagget bruges i URL'en. Husk at URI-kode værdier. For eksempel skal # i stedet repræsenteres som %23.
Nogle af disse felter er markeret READONLY - disse returneres af API'et, men kan ikke sættes.

GET /api/v1/hash-tags

Resource: HashTag as GET /api/v1/hash-tags Credit Cost: 1

Denne API bruger paginering, leveret af page query-parameteren. HashTags returneres i sider af 100, sorteret efter tag.

HashTag cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

HashTag Anmodningsstruktur

Copy

interface HashTagsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The page to fetch, starting with 0. **/
    page: number
}

HashTag Svarstruktur

Copy

interface HashTagsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The hashtags! **/
    hashTags: HashTag[]
}

PATCH /api/v1/hash-tags/:tag

Resource: HashTag as PATCH /api/v1/hash-tags/:tag Credit Cost: 1

Denne rute giver mulighed for at opdatere en enkelt HashTag.

HashTag Opdatering cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/some-`page`"
}'

HashTag Opdatering Anmodningsstruktur

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Opdatering Svarstruktur

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag' |  'already-exists'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete updated hashtag on success.
}

POST /api/v1/hash-tags

Resource: HashTag as POST /api/v1/hash-tags Credit Cost: 1

Denne rute giver mulighed for at tilføje en enkelt HashTag.

HashTag Oprettelse cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/hash-tags?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tag": "#example",
    "url": "https://example.com/some-page"
}'

HashTag Oprettelse Anmodningsstruktur

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Oprettelse Svarstruktur

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
    /** Included on failure. **/
    reason?: string
    hashTag?: HashTag; // We return the complete created hashtag on success.
}

POST /api/v1/hash-tags/bulk

Resource: HashTag as POST /api/v1/hash-tags/bulk Credit Cost: 1

Denne rute giver mulighed for at tilføje op til 100 HashTag-objekter på én gang.

HashTag Bulk Oprettelse cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/hash-tags/bulk?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "tags": [
        {
            "tag": "#example",
            "url": "https://example.com/some-page"
        }
    ]
}'

HashTag Bulk Oprettelse Anmodningsstruktur

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Bulk Oprettelse Svarstruktur

Copy

interface HashTagBulkPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist' | 'url-too-long' | 'invalid-tag'
    /** Included on failure. **/
    reason?: string
    results?: HashTagPostResponse[]; // We return a list of HashTagPostResponse objects for each provided tag.
}

DELETE /api/v1/hash-tags/:tag

Resource: HashTag as DELETE /api/v1/hash-tags/:tag Credit Cost: 1

Denne rute giver mulighed for at fjerne en HashTag via den angivne tag.

Bemærk at medmindre automatisk HashTag-oprettelse er deaktiveret, kan hashtags genskabes af en bruger, der angiver hashtagget, når de kommenterer.

HashTag Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/hash-tags/%23example_hash_tag?tenantId=demo&API_KEY=DEMO_API_SECRET'

HashTag Fjernelse Anmodningsstruktur

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Fjernelse Svarstruktur

Copy

interface HashTagDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-hash-tag' | 'tag-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

Moderatorstruktur

Et Moderator-objekt repræsenterer konfiguration for en moderator.

Der er tre typer moderatorer:

Administratorbrugere, der har isCommentModeratorAdmin-flaget.
SSO-brugere med isCommentModeratorAdmin-flaget.
Almindelige kommentatorer eller FastComments.com-brugere, der er inviteret som Moderatorer.

Moderator-strukturen bruges til at repræsentere Moderationstilstanden for anvendelsestilfælde 3.

Hvis du vil invitere en bruger til at være moderator via API'et, brug Moderator API'et ved at oprette en Moderator og invitere dem.

Hvis brugeren ikke har en FastComments.com-konto, vil invitations-e-mailen hjælpe dem med at blive sat op. Hvis de allerede har en konto, vil de få moderationsadgang til din tenant, og Moderator-objektets userId vil blive opdateret til at pege på deres bruger. Du vil ikke have API- adgang til deres bruger, da den i dette tilfælde tilhører dem selv og administreres af FastComments.com.

Hvis du kræver fuld styring af brugerens konto, anbefaler vi enten at bruge SSO eller tilføje dem som en Tenant Bruger og derefter tilføje et Moderator-objekt for at spore deres statistikker.

Moderator-strukturen kan bruges som en statistik-sporingsmekanisme for anvendelsestilfælde 1 og 2. Efter oprettelse af brugeren, tilføj et Moderator- objekt med deres userId defineret, og deres statistikker vil blive sporet på Kommentarmoderatorer-siden.

Strukturen for Moderator-objektet er som følger:

Moderator Struktur

Copy

interface Moderator {
    name: string
    email: string
    tenantId: string
    userId?: string|null
    acceptedInvite?: boolean
    markReviewedCount?: number
    deletedCount?: number
    markedSpamCount?: number
    approvedCount?: number
    editedCount?: number
    bannedCount?: number
    createdAt: string
    moderationGroupIds?: string[]|null
}

GET /api/v1/moderators/:id

Resource: Moderator as GET /api/v1/moderators/:id Credit Cost: 1

Denne rute returnerer en enkelt moderator efter deres id.

Moderator Efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Moderator Anmodningsstruktur

Copy

interface ModeratorByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator Svarstruktur

Copy

interface ModeratorByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    moderator?: Moderator
}

GET /api/v1/moderators

Resource: Moderator as GET /api/v1/moderators Credit Cost: 1

Denne API bruger paginering, leveret af skip query-parameteren. Moderatorer returneres i sider af 100, sorteret efter createdAt og id.

Prisen er baseret på antallet af returnerede moderatorer, koste 1 kredit pr. 10 returnerede moderatorer.

Moderator cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

Moderator Anmodningsstruktur

Copy

interface ModeratorsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of moderators to skip for pagination. **/
    skip?: number
}

Moderator Svarstruktur

Copy

interface ModeratorsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    moderators?: Moderator[]
}

PATCH /api/v1/moderators/:id

Resource: Moderator as PATCH /api/v1/moderators/:id Credit Cost: 1

Denne API-endpoint giver mulighed for at opdatere en Moderator efter id.

Opdatering af en Moderator har følgende begrænsninger:

Følgende værdier må ikke angives ved opdatering af en Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Når et userId er angivet, skal den bruger eksistere.
Når et userId er angivet, skal de tilhøre det samme tenantId, der er angivet i query-parametre.
To moderatorer i den samme tenant kan ikke tilføjes med den samme email.
Du må ikke ændre det tenantId, der er tilknyttet en Moderator.

Moderator PATCH cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

Moderator PATCH Anmodningsstruktur

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator PATCH Svarstruktur

Copy

interface ModeratorPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found';
    /** Included on failure. **/
    reason?: string
}

POST /api/v1/moderators

Resource: Moderator as POST /api/v1/moderators Credit Cost: 1

Denne rute giver mulighed for at tilføje en enkelt Moderator.

Oprettelse af en Moderator har følgende begrænsninger:

Et name og email skal altid angives. Et userId er valgfrit.
Følgende værdier må ikke angives ved oprettelse af en Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Når et userId er angivet, skal den bruger eksistere.
Når et userId er angivet, skal de tilhøre det samme tenantId, der er angivet i query-parametre.
To moderatorer i den samme tenant kan ikke tilføjes med den samme email.

Vi kan oprette en Moderator for en bruger, hvor vi kun kender e-mailen:

Moderator Opret via E-mail cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com"
}'

Eller vi kan oprette en Moderator for en bruger, der tilhører vores tenant, for at spore deres moderationsstatistikker:

Moderator Opret via Tenant Bruger cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com",
    "userId": "some-tenant-user-id"
}'

Moderator Oprettelse Anmodningsstruktur

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator Oprettelse Svarstruktur

Copy

interface ModeratorPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    moderator?: Moderator; // We return the complete created moderator on success.
}

POST /api/v1/moderators/:id/send-invite

Resource: Moderator as POST /api/v1/moderators/:id/send-invite Credit Cost: 10

Denne rute giver mulighed for at invitere en enkelt Moderator.

Følgende begrænsninger gælder for at sende en invitations-e-mail til en Moderator:

Moderatoren skal allerede eksistere.
fromName må ikke være længere end 100 tegn.

Bemærkninger:

Hvis en bruger med den angivne e-mail allerede eksisterer, vil de blive inviteret til at moderere din tenants kommentarer.
Hvis en bruger med den angivne e-mail ikke eksisterer, vil invitationslinket guide dem gennem oprettelse af deres konto.
Invitationen udløber efter 30 dage.

Vi kan oprette en Moderator for en bruger, hvor vi kun kender e-mailen:

Moderator Invitation cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/moderators/xyz/send-invite?tenantId=demo&API_KEY=DEMO_API_SECRET&fromName=Bob' \
  --header 'Content-Type: application/json'

Dette vil sende en e-mail som Bob hos TenantName inviterer dig til at være moderator...

Moderator Invitation Anmodningsstruktur

Copy

interface ModeratorSendInviteQueryParams {
    tenantId: string
    API_KEY: string
    /** The email sent to the user will appear to be sent from this name. **/
    fromName: string
}

Moderator Invitation Svarstruktur

Copy

interface ModeratorSendInviteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found | 'from-name-required' | 'from-name-invalid'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/moderators/:id

Resource: Moderator as DELETE /api/v1/moderators/:id Credit Cost: 5

Denne rute giver mulighed for at fjerne en Moderator efter id.

Moderator Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/moderators/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Moderator Fjernelse Anmodningsstruktur

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator Fjernelse Svarstruktur

Copy

interface ModeratorDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

Notifikationstællingsstruktur

Et NotificationCount-objekt repræsenterer antallet af ulæste notifikationer og metadata for en bruger.

Hvis der ikke er nogen ulæste notifikationer, vil der ikke være en NotificationCount for brugeren.

NotificationCount-objekter oprettes automatisk og kan ikke oprettes via API'et. De udløber også efter et år.

Du kan rydde en brugers antal ulæste notifikationer ved at slette deres NotificationCount.

Strukturen for NotificationCount-objektet er som følger:

NotificationCount Struktur

Copy

interface NotificationCount {
    id: string // user id
    count: number
    createdAt: string // date string
    expireAt: string // date string
}

GET /api/v1/notification-count/:user_id

Resource: NotificationCount as GET /api/v1/notification-count/:user_id Credit Cost: 1

Denne rute returnerer en enkelt NotificationCount efter bruger-id. Med SSO er bruger-id'et i formatet <tenant id>:<user id>.

Hvis der ikke er nogen ulæste notifikationer, vil der ikke være en NotificationCount - så du vil få en 404.

Dette er forskelligt fra notifications/count ved at det er meget hurtigere, men tillader ikke filtrering.

NotificationCount Efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
# -> {"status":"success","data":{"count":1,"createdAt":"2023-03-06T18:45:01.726Z","expireAt":"2024-03-06T01:25:01.726Z","id":"example"}}

NotificationCount Anmodningsstruktur

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

NotificationCount Svarstruktur

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Included on failure. **/
    reason?: string
    data?: NotificationCount
}

DELETE /api/v1/notification-count/:user_id

Resource: NotificationCount as DELETE /api/v1/notification-count/:user_id Credit Cost: 1

Denne rute sletter en enkelt NotificationCount efter bruger-id. Med SSO er bruger-id'et i formatet <tenant id>:<user id>.

Dette vil rydde brugerens antal ulæste notifikationer (den røde klokke i kommentar-widget'en vil falme ud, og tælleren forsvinder).

DELETE NotificationCount cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/notification-count/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'
# -> {"status":"success"}

NotificationCount Fjernelse Anmodningsstruktur

Copy

interface NotificationCountDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

NotificationCount Fjernelse Svarstruktur

Copy

interface NotificationCountDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

Notifikationsstruktur

Et Notification-objekt repræsenterer en notifikation for en bruger.

Notification-objekter oprettes automatisk og kan ikke oprettes via API'et. De udløber også efter et år. Notifikationer kan ikke slettes. De kan dog opdateres for at sætte viewed til false, og du kan forespørge efter viewed.

En bruger kan også fravælge notifikationer for en specifik kommentar ved at sætte optedOut i notifikationen til true. Du kan tilvælge igen ved at sætte den til false.

Der er forskellige notifikationstyper - tjek relatedObjectType og type.

Måderne notifikationer oprettes på er ret fleksible og kan udløses af mange scenarier (se NotificationType).

Per dags dato indebærer eksistensen af en Notification faktisk ikke, at en e-mail sendes eller bør sendes. I stedet bruges notifikationerne til notifikationsfeedet og relaterede integrationer.

Strukturen for Notification-objektet er som følger:

Notification Struktur

Copy

enum NotificationObjectType {
    Comment = 0,
    Profile = 1,
    Tenant = 2
}
enum NotificationType {
    /** If someone replied to you. **/
    RepliedToMe = 0,
    /** If someone replied anywhere in a thread (even children of children) of a thread you commented on. **/
    RepliedTransientChild = 1,
    /** If your comment was up-voted. **/
    VotedMyComment = 2,
    /** If a new comment is left on the root of a page you're subscribed to. **/
    SubscriptionReplyRoot = 3,
    /** If someone commented on your profile. **/
    CommentedOnProfile = 4,
    /** If you have a DM. **/
    DirectMessage = 5,
    /** TrialLimits is for tenant users only. **/
    TrialLimits = 6,
    /** If you were @mentioned. **/
    Mentioned = 7
}
interface Notification {
    id: string
    tenantId: string
    /** With SSO, the user id is in the format `<tenant id>:<user id>`. **/
    userId?: string
    /** When working with SSO, you only have to worry about `userId`. **/
    anonUserId?: string
    /** urlId is almost always defined. It is only optional for tenant-level notifications, which are infrequent. **/
    urlId?: string
    /** URL is cached for quick navigation to the source of the notification. **/
    url?: string
    /** Page Title is cached for quick reading of notification source. **/
    pageTitle?: string
    relatedObjectType: NotificationObjectType
    /** For example, comment id. **/
    relatedObjectId: string
    viewed: boolean
    createdAt: string // date string
    type: NotificationType
    fromCommentId?: string
    fromVoteId?: string
    /** fromUserName and fromUserAvatarSrc are cached here for quick displaying of the notification. They are updated when the user is updated. **/
    fromUserName: string
    fromUserId: string
    fromUserAvatarSrc?: string
    /** Set this to true to stop getting notifications for this object. **/
    optedOut?: boolean
}

GET /api/v1/notifications

Resource: Notification as GET /api/v1/notifications Credit Cost: 1

Denne rute returnerer op til 30 Notification-objekter sorteret efter createdAt, nyeste først.

Du kan filtrere efter userId. Med SSO er bruger-id'et i formatet <tenant id>:<user id>.

Ulæste Notifikationer For Bruger cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'

Notifications Anmodningsstruktur

Copy

interface NotificationsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Paginate by skipping records. **/
    skip?: number
    /** Filter by user. **/
    userId?: string
    /** Filter by urlId. **/
    urlId?: string
    /** Filter by source comment. **/
    fromCommentId?: string
    /** Filter by read/unread. **/
    viewed?: 'true' | 'false'
    /** Filter by type. **/
    type?: NotificationType
}

Notifications Svarstruktur

Copy

interface NotificationsGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    notifications?: Notification[]
}

GET /api/v1/notifications/count

Resource: Notification as GET /api/v1/notifications/count Credit Cost: 2

Denne rute returnerer et objekt, der indeholder antallet af notifikationer under en count-parameter.

Den er langsommere end /notification-count/ og dobbelt så mange kreditter, men tillader filtrering på flere dimensioner.

Du kan filtrere efter de samme parametre som /notifications-endpointet som userId. Med SSO er bruger-id'et i formatet <tenant id>:<user id>.

Ulæste Notifikationer Antal For Bruger cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false'

Ulæste Notifikationer Antal For Bruger For Specifik Side cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/notifications/count?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID&viewed=false&urlId=some-article-id-or-url'

Notification Count Anmodningsstruktur

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Filter by user. **/
    userId?: string
    /** Filter by urlId. **/
    urlId?: string
    /** Filter by source comment. **/
    fromCommentId?: string
    /** Filter by read/unread. **/
    viewed?: 'true' | 'false'
    /** Filter by type. **/
    type?: NotificationType
}

Notification Count Svarstruktur

Copy

interface NotificationCountGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    count?: number
}

PATCH /api/v1/notifications/:id

Resource: Notification as PATCH /api/v1/notifications/:id Credit Cost: 1

Denne API-endpoint giver mulighed for at opdatere en Notification efter id.

Opdatering af en Notification har følgende begrænsninger:

Du kan kun opdatere følgende felter:
- viewed
- optedOut

Notification PATCH cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/notifications/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "viewed": false,
}'

Notification PATCH Anmodningsstruktur

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Notification PATCH Svarstruktur

Copy

interface NotificationPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';
    /** Included on failure. **/
    reason?: string
}

Sidestruktur

Et Page-objekt repræsenterer den side, som mange kommentarer kan tilhøre. Dette forhold defineres af urlId.

En Page gemmer information såsom sidetitlen, kommentarantal og urlId.

Strukturen for Page-objektet er som følger:

Page Struktur

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** Setting this to null means all SSO users can see the page. An empty list means it is closed to all users. **/
    accessibleByGroupIds?: string[] | null
    /** Is this page closed for new comments? **/
    isClosed?: boolean
}

GET /api/v1/pages

Resource: Page as GET /api/v1/pages Credit Cost: 10

Du kan i øjeblikket kun hente alle sider (eller en enkelt side via /by-url-id) tilknyttet din konto. Hvis du ønsker mere finmasket søgning, kontakt os.

Pages cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET'

Pages Anmodningsstruktur

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Pages Svarstruktur

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    pages: Page[]
}

Nyttigt Tip

Comment API'et kræver et urlId. Du kan kalde Pages API'et først for at se, hvordan de tilgængelige urlId-værdier ser ud.

GET /api/v1/pages/by-url-id

Resource: Page as GET /api/v1/pages/by-url-id Credit Cost: 1

Individuelle sider kan hentes via deres tilsvarende urlId. Dette kan være nyttigt til at slå sidetitler eller kommentarantal op.

Page efter URL ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pages/by-url-id?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=example-id-or-url'

Page Efter URL ID Anmodningsstruktur

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Page efter URL ID Svarstruktur

Copy

interface PagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    page?: Page[] | null
}

Nyttigt Tip

Husk at URI-kode værdier som urlId.

PATCH /api/v1/pages/:id

Resource: Page as PATCH /api/v1/pages/:id Credit Cost: 1

Denne rute giver mulighed for at opdatere en enkelt Page. De tilsvarende kommentarer vil blive opdateret.

Page Opdatering cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/pages/my-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/some-page"
}'

Page Opdatering Anmodningsstruktur

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Page Opdatering Svarstruktur

Copy

interface PagePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-id' | 'page-does-not-exist' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large'
    /** Included on failure. **/
    reason?: string
    user?: Page; // We return the complete updated page on success.
}

Bemærkning

Nogle parametre i Page-objektet opdateres automatisk. Disse er tælle- og titelattributter. Tællere kan ikke opdateres via API'et, da de er beregnede værdier. Sidens title kan sættes via API'et, men vil blive overskrevet, hvis kommentar-widget'en bruges på en side med det samme urlId og en anden sidetitel.

POST /api/v1/pages

Resource: Page as POST /api/v1/pages Credit Cost: 1

Denne API-endpoint giver mulighed for at oprette sider.

Et almindeligt anvendelsestilfælde er adgangskontrol.

Bemærkninger:

Hvis du har kommenteret på en kommentartråd eller kaldt API'et for at oprette en Comment, har du allerede oprettet et Page-objekt! Du kan prøve at hente det via /by-url-id Page-ruten ved at angive det samme urlId, som blev sendt til kommentar-widget'en.
Page-strukturen indeholder nogle beregnede værdier. I øjeblikket er disse commentCount og rootCommentCount. De udfyldes automatisk og kan ikke sættes af API'et. Forsøg på at gøre det vil få API'et til at returnere en fejl.

Page POST cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/pages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Test Page",
    "url": "some0-url",
    "urlId": "page2",
    "accessibleByGroupIds": ["SOME_GROUP_ID"]
}'

Page POST Anmodningsstruktur

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Page POST Svarstruktur

Copy

interface PagePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-request' | 'internal' | 'invalid-input' | 'invalid-title' | 'extra-params' | 'accessible-by-group-ids-not-array' | 'too-many-group-ids' | 'group-id-too-large';
    /** Included on failure. **/
    reason?: string
    /** The created page. **/
    page?: Page
}

DELETE /api/v1/pages/:id

Resource: Page as DELETE /api/v1/pages/:id Credit Cost: 1

Denne rute giver mulighed for at fjerne en enkelt side efter id.

Bemærk at interaktion med kommentar-widget'en for en side med det samme urlId simpelthen vil genskabe Page problemfrit.

Page Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/pages/some-page-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Page Fjernelse Anmodningsstruktur

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Page Fjernelse Svarstruktur

Copy

interface PageDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'page-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

Ventende webhook-hændelse-struktur

Et PendingWebhookEvent-objekt repræsenterer en webhook-begivenhed i kø, der afventer.

PendingWebhookEvent-objekter oprettes automatisk og kan ikke oprettes manuelt via API'et. De udløber også efter et år. De kan slettes, hvilket fjerner opgaven fra køen.

Der er forskellige begivenhedstyper - tjek eventType (OutboundSyncEventType) og type (OutboundSyncType).

Et almindeligt anvendelsestilfælde for dette API er at implementere brugerdefineret overvågning. Du vil måske kalde /count-endpointet periodisk for at polle det udestående antal for givne filtre.

Strukturen for PendingWebhookEvent-objektet er som følger:

PendingWebhookEvent Struktur

Copy

enum OutboundSyncEventType {
    Create: 0,
    Delete: 1,
    Update: 2
}
enum OutboundSyncType {
    /** WordPress-specific sync task. **/
    WP: 0,
    Webhook: 1
}
interface PendingWebhookEvent {
    id: string
    /** The comment id associated with the event. **/
    commentId: string
    /** The comment object for the event at the time of the event. We started adding these in Nov 2023. **/
    comment: Comment
    /** An external id that may be associated with the comment. **/
    externalId: string | null
    createdAt: Date
    tenantId: string
    attemptCount: number
    /** Set before first attempt, and after every failure. **/
    nextAttemptAt: Date
    /** Whether this is a creation, deletion, or update event... **/
    eventType: OutboundSyncEventType
    /** The type of sync to perform (WordPress, call API, etc). **/
    type: OutboundSyncType
    /** The domain that matched the comment. We use this domain to pick the API key. **/
    domain: string
    /** The last error that occurred. This type is untyped and is a "dump" of whatever happened. Usually it contains an object with statusCode, body, and a headers map. **/
    lastError: object | null
}

GET /api/v1/pending-webhook-events

Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events Credit Cost: 2

Denne rute returnerer en liste over afventende webhook-begivenheder under en pendingWebhookEvents-parameter.

Denne API bruger paginering, leveret af skip-parameteren. PendingWebhookEvents returneres i sider af 100, sorteret efter createdAt nyeste først.

PendingWebhookEvent cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events?tenantId=demo&API_KEY=DEMO_API_SECRET'

PendingWebhookEvent Anmodningsstruktur

Copy

interface PendingWebhookEventsGetQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Query for events with an attempt count greater than the specified number. **/
    attemptCountGT?: number
}

PendingWebhookEvent Svarstruktur

Copy

interface PendingWebhookEventsGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    pendingWebhookEvents?: PendingWebhookEvent[]
}

GET /api/v1/pending-webhook-events/count

Resource: PendingWebhookEvent as GET /api/v1/pending-webhook-events/count Credit Cost: 2

Denne rute returnerer et objekt, der indeholder antallet af afventende webhook-begivenheder under en count-parameter.

Du kan filtrere efter de samme parametre som /pending-webhook-events-endpointet

PendingWebhookEvent Count cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events/count?tenantId=demo&API_KEY=DEMO_API_SECRET'

PendingWebhookEvent Count Anmodningsstruktur

Copy

interface PendingWebhookEventsCountQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Query for events with an attempt count greater than the specified number. **/
    attemptCountGT?: number
}

PendingWebhookEvent Count Svarstruktur

Copy

interface PendingWebhookEventsCountResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    count?: number
}

DELETE /api/v1/pending-webhook-events/:id

Resource: PendingWebhookEvent as DELETE /api/v1/pending-webhook-events/:id Credit Cost: 1

Denne rute tillader sletning af en enkelt PendingWebhookEvent.

Hvis du har brug for massesletning, kald GET API'et med paginering og kald derefter dette API sekventielt.

DELETE PendingWebhookEvent cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/pending-webhook-events/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET'

Delete PendingWebhookEvent Anmodningsstruktur

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Delete PendingWebhookEvent Svarstruktur

Copy

interface PendingWebhookEventDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

SSO-brugerstruktur

FastComments giver en letanvendelig SSO-løsning. Opdatering af en brugers information med den HMAC-baserede integration er så enkelt som at have brugeren indlæse siden med en opdateret payload.

Det kan dog være ønskeligt at administrere en bruger uden for det flow for at forbedre konsistensen af din applikation.

SSO User API'et giver en måde at CRUD objekter, som vi kalder SSOUsers. Disse objekter er forskellige fra almindelige Users og holdes adskilt for typesikkerhed.

Strukturen for SSOUser-objektet er som følger:

SSOUser Struktur

Copy

interface SSOUser {
    id: string
    username: string
    email?: string
    websiteUrl?: string
    signUpDate: number
    createdFromUrlId?: string
    loginCount?: number
    avatarSrc?: string
    optedInNotifications?: boolean
    optedInSubscriptionNotifications?: boolean
    displayLabel?: string
    displayName?: string
    isAccountOwner?: boolean // Admin permission - SSO users with this flag are billed as SSO Admins (separate from regular SSO users)
    isAdminAdmin?: boolean // Admin permission - SSO users with this flag are billed as SSO Admins (separate from regular SSO users)
    isCommentModeratorAdmin?: boolean // Moderator permission - SSO users with this flag are billed as SSO Moderators (separate from regular SSO users)
    /** If null, Access Control will not be applied to the user. If an empty list, this user will not be able to see any pages or @mention other users. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** Don't let other users see this user's activity, including comments, on their profile. Default is true to provide secure profiles by default. **/
    isProfileActivityPrivate?: boolean
    /** Don't let other users leave comments on the user's profile, or see existing profile comments. Default false. **/
    isProfileCommentsPrivate?: boolean
    /** Don't let other users send direct messages to this user. Default false. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** Optional configuration for user badges. **/
    badgeConfig?: {
        /** Array of badge IDs to assign to the user. Limited to 30 badges. Order is respected. **/
        badgeIds: string[]
        /** If true, replaces all existing displayed badges with the provided ones. If false, adds to existing badges. **/
        override?: boolean
        /** If true, updates badge display properties from tenant configuration. **/
        update?: boolean
    }
}

Fakturering for SSO-brugere

SSO-brugere faktureres forskelligt baseret på deres tilladelsesflags:

Almindelige SSO-brugere: Brugere uden admin- eller moderatortilladelser faktureres som almindelige SSO-brugere
SSO-administratorer: Brugere med isAccountOwner eller isAdminAdmin flags faktureres separat som SSO-administratorer (samme sats som almindelige tenant-administratorer)
SSO-moderatorer: Brugere med isCommentModeratorAdmin flag faktureres separat som SSO-moderatorer (samme sats som almindelige moderatorer)

Vigtigt: For at forhindre dobbeltfakturering deduplikerer systemet automatisk SSO-brugere mod almindelige tenant-brugere og moderatorer efter e-mailadresse. Hvis en SSO-bruger har samme e-mail som en almindelig tenant-bruger eller moderator, vil de ikke blive faktureret to gange.

Adgangskontrol

Brugere kan opdeles i grupper. Dette er hvad groupIds-feltet er til, og det er valgfrit.

@Omtaler

Som standard vil @mentions bruge username til at søge efter andre sso-brugere, når @-tegnet skrives. Hvis displayName bruges, vil resultater, der matcher username, blive ignoreret, når der er et match for displayName, og @mention søgeresultaterne vil bruge displayName.

Abonnementer

Med FastComments kan brugere abonnere på en side ved at klikke på klokkeikonet i kommentar-widget'en og klikke Abonner.

Med en almindelig bruger sender vi dem notifikations-e-mails baseret på deres notifikationsindstillinger.

Med SSO-brugere opdeler vi dette af hensyn til bagudkompatibilitet. Brugere vil kun få sendt disse yderligere abonnementsnotifikations- e-mails, hvis du sætter optedInSubscriptionNotifications til true.

Badges

Du kan tildele badges til SSO-brugere ved hjælp af badgeConfig-egenskaben. Badges er visuelle indikatorer, der vises ved siden af en brugers navn i kommentarer.

badgeIds - Et array af badge-ID'er til at tildele brugeren. Disse skal være gyldige badge-ID'er oprettet i din FastComments-konto. Begrænset til 30 badges.
override - Hvis sand, vil alle eksisterende badges, der vises på kommentarer, blive erstattet med de angivne. Hvis falsk eller udeladt, vil de angivne badges blive tilføjet til eventuelle eksisterende badges.
update - Hvis sand, vil badge-visningsegenskaber blive opdateret fra tenant-konfigurationen, når brugeren logger ind.

GET /api/v1/sso-users

Resource: SSOUser as GET /api/v1/sso-users Credit Cost: 10

Denne rute returnerer SSO-brugere i sider af 100. Paginering leveres via skip-parameteren. Brugere sorteres efter deres signUpDate og id.

SSOUsers cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUsers Anmodningsstruktur

Copy

interface SSOUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    skip?: number
}

SSOUsers Svarstruktur

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    users: SSOUser[]
}

GET /api/v1/sso-users/by-id/:id

Resource: SSOUser as GET /api/v1/sso-users/by-id/:id Credit Cost: 1

Denne rute returnerer en enkelt SSO-bruger efter deres id.

SSOUser Efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-id/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Anmodningsstruktur

Copy

interface SSOUserRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Svarstruktur

Copy

interface SSOUserByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user: SSOUser
}

GET /api/v1/sso-users/by-email/:email

Resource: SSOUser as GET /api/v1/sso-users/by-email/:email Credit Cost: 1

Denne rute returnerer en enkelt SSO-bruger efter deres e-mail.

SSOUser Efter E-mail cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/sso-users/by-email/someone@somewhere.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Anmodningsstruktur

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Svarstruktur

Copy

interface SSOUserByEmailResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-email' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user: SSOUser
}

PATCH /api/v1/sso-users/:id

Resource: SSOUser as PATCH /api/v1/sso-users/:id Credit Cost: 1

Denne rute giver mulighed for at opdatere en enkelt SSO-bruger.

SSOUser Opdatering cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "notfordperfect"
}'

SSOUser Opdatering Anmodningsstruktur

Copy

interface SSOUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

SSOUser Opdatering Svarstruktur

Copy

interface SSOUserPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the complete updated user on success.
}

POST /api/v1/sso-users

Resource: SSOUser as POST /api/v1/sso-users Credit Cost: 1

Denne rute giver mulighed for at oprette en enkelt SSO-bruger.

Forsøg på at oprette to brugere med det samme ID vil resultere i en fejl.

SSOUser Oprettelse cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/sso-users?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "my-user-id",
    "username": "fordperfect",
    "displayName": "Ford Perfect",
    "email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

I dette eksempel angiver vi groupIds til adgangskontrol, men dette er valgfrit.

SSOUser Oprettelse Anmodningsstruktur

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Oprettelse Svarstruktur

Copy

interface SSOUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the created user on success.
}

Integrationsbemærkning

Data sendt af API'et kan tilsidesættes simpelthen ved at sende en anden SSO User HMAC payload. For eksempel, hvis du sætter et brugernavn via API'et, men derefter sender et andet via SSO-flowet ved sideindlæsning, vil vi automatisk opdatere deres brugernavn.

Vi vil ikke opdatere brugerparametre i dette flow, medmindre du eksplicit angiver dem eller sætter dem til null (ikke undefined).

PUT /api/v1/sso-users/:id

Resource: SSOUser as PUT /api/v1/sso-users Credit Cost: 1

Denne rute giver mulighed for at opdatere en enkelt SSO-bruger.

SSOUser Opdatering cURL Eksempel

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/sso-users/my-user-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "fordperfect",
    "displayName": "Ford Perfect",
    "email": "fordperfect@galaxy.com",
    "groupIds": ["some-optional-group-id"]
}'

I dette eksempel angiver vi groupIds til adgangskontrol, men dette er valgfrit.

SSOUser Opdatering Anmodningsstruktur

Copy

interface SSOUserPutQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

SSOUser Opdatering Svarstruktur

Copy

interface SSOUserPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the update user on success.
}

DELETE /api/v1/sso-users/:id

Resource: SSOUser as DELETE /api/v1/sso-users/:id Credit Cost: 1

Denne rute giver mulighed for at fjerne en enkelt SSO-bruger efter deres id.

Bemærk at indlæsning af kommentar-widget'en igen med en payload for denne bruger simpelthen vil genskabe brugeren problemfrit.

Sletning af brugerens kommentarer er mulig via deleteComments query-parameteren. Bemærk at hvis dette er sandt:

Alle brugerens kommentarer vil blive slettet live.
Alle underordnede (nu forældreløse) kommentarer vil blive slettet eller anonymiseret baseret på hver kommentars tilknyttede sidekonfiguration. For eksempel, hvis trådsletningstilstand er "anonymize", så forbliver svar, og brugerens kommentarer vil blive anonymiseret. Dette gælder kun, når commentDeleteMode er Remove (standardværdien).
creditsCost bliver 2.

Anonymiserede Kommentarer

Du kan beholde brugerens kommentarer, men blot anonymisere dem ved at sætte commentDeleteMode=1.

Hvis brugerens kommentarer er anonymiseret, så sættes følgende værdier til null:

- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badges

isDeleted og isDeletedUser sættes til true.

Ved rendering vil kommentar-widget'en bruge DELETED_USER_PLACEHOLDER (standard: "[deleted]") for brugerens navn og DELETED_CONTENT_PLACEHOLDER for kommentaren. Disse kan tilpasses via Widget Customization UI.

Eksempler

SSOUser Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/sso-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

SSOUser Fjernelse Anmodningsstruktur

Copy

enum SSOUserCommentDeleteMode {
    Remove = 0, // default
    Anonymize = 1
}
interface SSOUsersDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** You can set this to true to also delete the user's comments. This will double the credit cost. **/
    deleteComments?: 'true' | 'false'
    /** You can set this as desired to determine how to handle the user's comments. **/
    commentDeleteMode?: SSOUserCommentDeleteMode
}

SSOUser Fjernelse Svarstruktur

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
    user?: SSOUser; // We return the removed user on success.
}

Abonnementsstruktur

Et Subscription-objekt repræsenterer et abonnement for en bruger.

Subscription-objekter oprettes, når en bruger klikker på notifikationsklokken i kommentar-widget'en og klikker "Abonner på denne side".

Abonnementer kan også oprettes via API'et.

At have et Subscription-objekt medfører, at Notification-objekter genereres, og e-mails sendes, når nye kommentarer efterlades på roden af den tilknyttede side, som Subscription er for. Afsendelse af e-mails afhænger af brugertypen. For almindelige brugere afhænger dette af optedInNotifications. For SSO-brugere afhænger dette af optedInSubscriptionNotifications. Bemærk at nogle applikationer måske ikke har konceptet om en web-tilgængelig side, i hvilket tilfælde du blot skal sætte urlId til id'et for det element, du abonnerer på (samme værdi for urlId som du ville sende til kommentar-widget'en).

Strukturen for Subscription-objektet er som følger:

Subscription Struktur

Copy

interface Subscription {
    id: string
    tenantId: string
    /** With SSO, the user id is in the format `<tenant id>:<user id>`. **/
    userId: string
    anonUserId?: string
    urlId: string
    url?: string
    pageTitle?: string
    createdAt: string // date string
}

GET /api/v1/subscriptions/:id

Resource: Subscription as GET /api/v1/subscriptions Credit Cost: 1

Denne rute returnerer op til 30 Subscription-objekter sorteret efter createdAt, nyeste først.

Du kan filtrere efter userId. Med SSO er bruger-id'et i formatet <tenant id>:<user id>.

Subscriptions For Bruger cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=SOME_USER_ID'

Subscriptions Anmodningsstruktur

Copy

interface SubscriptionsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Paginate by skipping records. **/
    skip?: number
    /** Filter by user. **/
    userId?: string
}

Subscriptions Svarstruktur

Copy

interface SubscriptionsGetResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
    subscriptions?: Subscription[]
}

POST /api/v1/subscriptions

Resource: Subscription as POST /api/v1/subscriptions Credit Cost: 1

Dette API-endpoint giver mulighed for at oprette et Subscription. Bemærk at en bruger kun kan have ét abonnement pr. side, da flere er overflødige, og forsøg på at oprette mere end ét abonnement for den samme bruger til den samme side vil resultere i en fejl.

Oprettelse af et abonnement vil resultere i, at Notification-objekter oprettes, når en ny kommentar efterlades på roden af det abonnerede urlId (når kommentar parentId er null).

Subscription POST cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/subscriptions?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "tenantId:test-user-id",
    "urlId": "some-page-id-or-url",
    "url": "https://example.com/page",
    "pageTitle": "Some Example Page!"
}'

Subscription POST Anmodningsstruktur

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Subscription POST Svarstruktur

Copy

interface SubscriptionPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'unauthorized' | 'not-found';
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/subscriptions/:id

Resource: Subscription as DELETE /api/v1/subscriptions Credit Cost: 1

Denne rute sletter et enkelt Subscription-objekt efter id.

Subscription Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/subscriptions/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Subscription Fjernelse Anmodningsstruktur

Copy

interface SubscriptionsDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Subscription Fjernelse Svarstruktur

Copy

interface SubscriptionDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'unauthorized' | 'unexpected-param' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

Lejers daglige forbrug - struktur

Et TenantDailyUsage-objekt repræsenterer forbruget for en tenant på en given dag. Hvis der ikke var nogen aktivitet for en given tenant på en given dag, vil den dag ikke have et TenantDailyUsage-objekt.

TenantDailyUsage-objektet er ikke realtid og kan være minutter efter det faktiske forbrug.

Strukturen for TenantDailyUsage-objektet er som følger:

TenantDailyUsage Struktur

Copy

export interface TenantDailyUsage {
    yearNumber: number
    monthNumber: number
    dayNumber: number
    commentFetchCount?: number
    commentCreateCount?: number
    conversationCreateCount?: number
    voteCount?: number
    accountCreatedCount?: number
    userMentionSearch?: number
    hashTagSearch?: number
    gifSearchTrending?: number
    gifSearch?: number
    apiCreditsUsed?: number
    createdAt: string
    billed: boolean
    /** Ignored for billing. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

Resource: TenantDailyUsage as GET /api/v1/tenant-daily-usage Credit Cost: 1

Denne rute giver mulighed for at søge efter forbruget for en tenant efter år, måned og dag. Op til 365 objekter kan returneres, og omkostningen er 1 api-kredit pr. 10 objekter.

Svarobjekter sorteres efter datoen de er oprettet (de ældste først).

TenantDailyUsage Søgning cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-daily-usage?tenantId=demo&API_KEY=DEMO_API_SECRET&yearNumber=2022&monthNumber=2&dayNumber=10'

TenantDailyUsage Anmodningsstruktur

Copy

interface TenantDailyUsageQueryParams {
    tenantId: string
    API_KEY: string
    /** Based on UTC. **/
    yearNumber?: number
    /** Zero-based. Based on UTC. **/
    monthNumber?: number
    /** One-based. Based on UTC. **/
    dayNumber?: number
}

TenantDailyUsage Svarstruktur

Copy

interface TenantDailyUsageResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    tenantDailyUsages: TenantDailyUsage[]
}

Lejerstruktur

Tenant definerer en FastComments.com-kunde. De kan oprettes via API'et af tenants med white labeling adgang. White labeled tenants kan ikke oprette andre white labeled tenants (kun ét niveau af indlejring er tilladt).

Strukturen for Tenant-objektet er som følger:

Tenant Struktur

Copy

export enum SiteType {
    Unknown = 0,
    WordPress = 1
}
/** This can also be handled via the DomainConfig API. **/
export interface TenantDomainConfig {
    domain: string
    emailFromName?: string
    emailFromEmail?: string
    createdAt?: string,
    siteType?: FastCommentsSiteType, // you probably want Unknown
    logoSrc?: string, // raw image path
    logoSrc100px?: string, // resized for thumbnails
    footerUnsubscribeURL?: string,
    emailHeaders?: Record<string, string>,
    disableUnsubscribeLinks?: boolean,
    dkim?: {
        domainName: string,
        keySelector: string,
        privateKey: string
    }
}
export interface TenantBillingInfo {
    name: string
    address: string
    city: string
    state: string
    zip: string
    country: string
}
export enum TenantPaymentFrequency {
    Monthly = 0,
    Annually = 1
}
export interface Tenant {
    id: string
    name: string
    email?: string
    signUpDate: number; // number due to "legacy" reasons
    packageId?: string | null
    paymentFrequency?: TenantPaymentFrequency
    billingInfoValid?: boolean
    billingHandledExternally?: boolean
    createdBy?: string
    isSetup?: boolean
    domainConfiguration: FastCommentsAPITenantDomainConfig[]
    billingInfo?: FastCommentsAPITenantBillingInfo
    stripeCustomerId?: string
    stripeSubscriptionId?: string
    stripePlanId?: string
    enableProfanityFilter?: boolean
    enableSpamFilter?: boolean
    lastBillingIssueReminderDate?: string
    removeUnverifiedComments?: boolean
    unverifiedCommentsTTLms?: number
    commentsRequireApproval?: boolean
    autoApproveCommentOnVerification?: boolean
    sendProfaneToSpam?: boolean
    /** @readonly - Is calculated based on packageId. **/
    hasFlexPricing?: boolean
    /** @readonly **/
    flexLastBilledAmount?: number
    /** @readonly - Is calculated based on packageId. **/
    hasAuditing?: boolean
    /** You can store a key value pair with the tenant which you can use to query. Keys cannot contain "." or "$", or be longer than 100 chars. Values may not be longer than 2k chars. **/
    meta?: Record<string, string | null>
}

GET /api/v1/tenants/:id

Resource: Tenant as GET /api/v1/tenants/:id Credit Cost: 1

Denne rute returnerer en enkelt Tenant efter id.

Tenant Efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Tenant Anmodningsstruktur

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant Svarstruktur

Copy

interface TenantByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
    tenant?: Tenant
}

GET /api/v1/tenants

Resource: Tenant as GET /api/v1/tenants Credit Cost: 1

Dette API returnerer tenants, der administreres af din tenant.

Paginering leveres af skip-forespørgselsparameteren. Tenants returneres i sider af 100, sorteret efter signUpDate og id.

Omkostningen er baseret på antallet af returnerede tenants og koster 1 kredit pr. 10 returnerede tenants.

Tenant cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

Du kan definere meta-parametre på Tenant-objekterne og forespørge efter matchende tenants. For eksempel, for nøglen someKey og meta-værdien some-value, kan vi konstruere et JSON-objekt med dette nøgle/værdi-par og derefter URI-kode det som en forespørgselsparameter for at filtrere:

Tenant Forespørgsel efter Meta cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET&meta=%7B%22someKey%22%3A%22some-value%22%7D'

Tenant Anmodningsstruktur

Copy

interface TenantsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenants to skip for pagination. **/
    skip?: number
    /** Filter by meta params. **/
    meta?: string
}

Tenant Svarstruktur

Copy

interface TenantsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenants?: Tenant[]
}

POST /api/v1/tenants

Resource: Tenant as POST /api/v1/tenants Credit Cost: 1

Denne rute giver mulighed for at tilføje en enkelt Tenant.

Oprettelse af en Tenant har følgende begrænsninger:

Et name er påkrævet.
domainConfiguration er påkrævet.
Følgende værdier må ikke angives ved oprettelse af en Tenant:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
signUpDate må ikke være i fremtiden.
name må ikke være længere end 200 tegn.
email må ikke være længere end 300 tegn.
email skal være unik på tværs af alle FastComments.com tenants.
Du kan ikke oprette tenants, hvis den overordnede tenant ikke har en gyldig TenantPackage defineret.
- Hvis din tenant blev oprettet via FastComments.com, bør dette ikke være et problem.
Du kan ikke oprette flere tenants end defineret under maxWhiteLabeledTenants i din pakke.
Du skal angive tenantId-forespørgselsparameteren, som er id'et for din overordnede tenant med white labeling aktiveret.

Vi kan oprette en Tenant med kun få parametre:

Tenant Oprettelse cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some Name",
    "email": "someone@someone.com",
    "domainConfiguration": [ { "domain": "somedomain.com" } ]
}'

Tenant Oprettelse Anmodningsstruktur

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant Oprettelse Svarstruktur

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info'
    /** Included on failure. **/
    reason?: string
    tenant?: Tenant; // We return the complete created tenant on success.
}

PATCH /api/v1/tenants/:id

Resource: Tenant as PATCH /api/v1/tenants/:id Credit Cost: 1

Dette API-endpoint giver mulighed for at opdatere en Tenant efter id.

Opdatering af en Tenant har følgende begrænsninger:

Følgende værdier kan ikke opdateres:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
- managedByTenantId
signUpDate må ikke være i fremtiden.
name må ikke være længere end 200 tegn.
email må ikke være længere end 300 tegn.
email skal være unik på tværs af alle FastComments.com tenants.
Når du sætter billingInfoValid til true, skal billingInfo angives i den samme anmodning.
Du kan ikke opdatere packageId tilknyttet din egen tenant.
Du kan ikke opdatere paymentFrequency tilknyttet din egen tenant.

Tenant PATCH cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

Tenant PATCH Anmodningsstruktur

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant PATCH Svarstruktur

Copy

interface TenantPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'unexpected-param' | 'sign-up-date-in-future' | 'payment-frequency-invalid' | 'cannot-change-payment-frequency' | 'name-invalid' | 'email-invalid' | 'email-taken' | 'no-package' | 'invalid-package' | 'unauthorized' | 'tenant-limit-reached' | 'cannot-move-tenant' | 'cannot-change-package' | 'invalid-billing-info';
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenants/:id

Resource: Tenant as DELETE /api/v1/tenants/:id Credit Cost: 1,000

Denne rute giver mulighed for fjernelse af en Tenant og alle tilknyttede data (brugere, kommentarer osv.) efter id.

Følgende begrænsninger eksisterer omkring fjernelse af tenants:

Tenant skal være din egen eller en white label tenant, som du administrerer.
sure-forespørgselsparameteren skal være sat til true.

Tenant Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenants/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

Tenant Fjernelse Anmodningsstruktur

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant Fjernelse Svarstruktur

Copy

interface TenantDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'unsure'
    /** Included on failure. **/
    reason?: string
}

Lejerpakke-struktur

TenantPackage definerer pakkeinformation tilgængelig for en Tenant. En tenant kan have mange pakker tilgængelige, men kun én i brug på et givent tidspunkt.

En Tenant kan ikke bruges til nogen produkter, før dens packageId peger på en gyldig TenantPackage.

Der er to typer TenantPackage-objekter:

Fastpris-pakker - hvor hasFlexPricing er false.
Fleksibel prissætning - hvor hasFlexPricing er true.

I begge tilfælde defineres grænser på kontoen ved hjælp af pakken, dog med Flex opkræves tenant en basispris plus hvad de brugte, defineret af flex*-parametrene.

En tenant kan have flere tenant-pakker og have mulighed for selv at ændre pakken fra Faktureringsinformationssiden.

Hvis du selv vil håndtere fakturering for tenants, skal du stadig definere en pakke for hver tenant for at definere deres grænser. Sæt blot billingHandledExternally til true på Tenant, og de vil ikke kunne ændre deres faktureringsinformation eller aktive pakke selv.

Du kan ikke oprette pakker med højere grænser end den overordnede tenant.

Strukturen for TenantPackage-objektet er som følger:

TenantPackage Struktur

Copy

export interface TenantPackage {
    id: string
    name: string
    tenantId: string
    createdAt: string
    monthlyCostUSD: number
    yearlyCostUSD: number
    monthlyStripePlanId?: string
    yearlyStripePlanId?: string
    maxMonthlyPageLoads: number
    maxMonthlyAPICredits: number
    maxMonthlyComments: number
    maxConcurrentUsers: number
    maxTenantUsers: number
    maxSSOUsers: number
    maxModerators: number
    maxDomains: number
    maxWhiteLabeledTenants: number
    hasWhiteLabeling: boolean
    hasDebranding: boolean
    forWhoText: string
    featureTaglines: string[]
    hasAuditing: boolean
    hasFlexPricing: boolean
    flexPageLoadCostCents?: null
    flexPageLoadUnit?: null
    flexCommentCostCents?: null
    flexCommentUnit?: null
    flexSSOUserCostCents?: null // Cost per regular SSO user (without admin/moderator permissions)
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexSSOAdminCostCents?: null // Cost per SSO user with admin permissions (isAccountOwner or isAdminAdmin flags)
    flexSSOAdminUnit?: null
    flexSSOModeratorCostCents?: null // Cost per SSO user with moderator permissions (isCommentModeratorAdmin flag)
    flexSSOModeratorUnit?: null
    flexMinimumCostCents?: null
}

GET /api/v1/tenant-packages/:id

Resource: TenantPackage as GET /api/v1/tenant-packages/:id Credit Cost: 1

Denne rute returnerer en enkelt Tenant Package efter id.

TenantPackage Efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantPackage Anmodningsstruktur

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage Svarstruktur

Copy

interface TenantPackageByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    tenantPackage: TenantPackage
}

GET /api/v1/tenant-packages

Resource: TenantPackage as GET /api/v1/tenant-packages Credit Cost: 1

Dette API bruger paginering, leveret af skip-forespørgselsparameteren. TenantPackages returneres i sider af 100, sorteret efter createdAt og id.

Omkostningen er baseret på antallet af returnerede tenant-pakker og koster 1 kredit pr. 10 returnerede tenant-pakker.

TenantPackage cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&skip=0&API_KEY=DEMO_API_SECRET'

TenantPackage Anmodningsstruktur

Copy

interface TenantPackagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenant packages to skip for pagination. **/
    skip?: number
}

TenantPackage Svarstruktur

Copy

interface TenantPackagesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenantPackages?: TenantPackage[]
}

POST /api/v1/tenant-packages

Resource: TenantPackage as POST /api/v1/tenant-packages Credit Cost: 1

Denne rute giver mulighed for at tilføje en enkelt TenantPackage.

Oprettelse af en TenantPackage har følgende begrænsninger:

Følgende parametre er påkrævet:
- name
- tenantId
- monthlyCostUSD - Kan være null.
- yearlyCostUSD - Kan være null.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - Hvis true, så er alle flex*-parametre påkrævet.
name må ikke være længere end 50 tegn.
Hvert forWhoText-element må ikke være længere end 200 tegn.
Hvert featureTaglines-element må ikke være længere end 100 tegn.
TenantPackage skal være "mindre" end den overordnede tenant. For eksempel skal alle max*-parametre have lavere værdier end den overordnede tenant.
En white labeled tenant kan have maksimalt fem pakker.
Kun tenants med white labeling adgang kan oprette en TenantPackage.
Du kan ikke tilføje pakker til din egen tenant. :)

Vi kan oprette en TenantPackage som følger:

TenantPackage Oprettelse via Email cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Default Package",
  "tenantId": "some-child-tenant-id",
  "monthlyCostUSD": null,
  "yearlyCostUSD": null,
  "maxMonthlyPageLoads": 50000,
  "maxMonthlyAPICredits": 50000,
  "maxMonthlyComments": 50000,
  "maxConcurrentUsers": 50000,
  "maxTenantUsers": 10,
  "maxSSOUsers": 50000,
  "maxModerators": 100,
  "maxDomains": 3,
  "hasWhiteLabeling": false,
  "hasDebranding": true,
  "forWhoText": "For Everyone",
  "featureTaglines": [
    "Some Tag",
    "Some Other Tag"
  ],
  "hasFlexPricing": true,
  "flexPageLoadCostCents": 100,
  "flexPageLoadUnit": 100000,
  "flexCommentCostCents": 100,
  "flexCommentUnit": 100000,
  "flexSSOUserCostCents": 100,
  "flexSSOUserUnit": 1000,
  "flexAPICreditCostCents": 100,
  "flexAPICreditUnit": 50000,
  "flexModeratorCostCents": 500,
  "flexModeratorUnit": 1,
  "flexAdminCostCents": 1000,
  "flexAdminUnit": 1,
  "flexDomainCostCents": 1000,
  "flexDomainUnit": 1,
  "flexMinimumCostCents": 99
}'

TenantPackage Oprettelse Anmodningsstruktur

Copy

interface TenantPackagePostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage Oprettelse Svarstruktur

Copy

interface TenantPackagePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param'
    /** Included on failure. **/
    reason?: string
    tenantPackage?: TenantPackage; // We return the complete created tenant package on success.
}

PATCH /api/v1/tenant-packages/:id

Resource: TenantPackage as PATCH /api/v1/tenant-packages/:id Credit Cost: 1

Dette API-endpoint giver mulighed for at opdatere en TenantPackage efter id.

Opdatering af en TenantPackage har følgende begrænsninger:

Hvis du sætter hasFlexPricing til true, så er alle flex*-parametre påkrævet i den samme anmodning.
name må ikke være længere end 50 tegn.
Hvert forWhoText-element må ikke være længere end 200 tegn.
Hvert featureTaglines-element må ikke være længere end 100 tegn.
TenantPackage skal være "mindre" end den overordnede tenant. For eksempel skal alle max*-parametre have lavere værdier end den overordnede tenant.
Du kan ikke ændre tenantId tilknyttet en TenantPackage.

TenantPackage PATCH cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some New Name",
}'

TenantPackage PATCH Anmodningsstruktur

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage PATCH Svarstruktur

Copy

interface TenantPackagePatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unexpected-param' | 'not-found' | 'white-labeling-not-allowed' | 'name-too-long' | 'for-who-text-too-long' | 'feature-tag-lines-too-long' | 'no-package' | 'invalid-package' | 'unauthorized' | 'child-tenant-too-large' | 'flex-param-missing' | 'unexpected-flex-param' | 'package-limit-reached' | 'flex-param-missing' | 'unexpected-flex-param';
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenant-packages/:id

Resource: TenantPackage as DELETE /api/v1/tenant-packages/:id Credit Cost: 5

Denne rute giver mulighed for fjernelse af en TenantPackage efter id.

Du kan ikke fjerne en TenantPackage, der er i brug (en tenants packageId peger på pakken). Opdater Tenant først.

TenantPackage Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-packages/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantPackage Fjernelse Anmodningsstruktur

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage Fjernelse Svarstruktur

Copy

interface TenantPackageDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized' | 'package-in-use'
    /** Included on failure. **/
    reason?: string
}

Lejerbrugerstruktur

TenantUser definerer en User, som administreres af en specifik tenant. Deres konto er under fuld kontrol af den tenant, de er associeret med, og deres konto kan opdateres eller slettes via UI'et eller API'et.

Tenant-brugere kan være administratorer med alle tilladelser og adgang til Tenant, eller de kan være begrænset til specifikke tilladelser til at moderere kommentarer, tilgå API-nøgler osv.

Strukturen for TenantUser-objektet er som følger:

TenantUser Struktur

Copy

/** This is for notifications. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** A link to the commenter's blog, for example. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** Does the user receive help requests from commenters? **/
    isHelpRequestAdmin: boolean
    isAccountOwner: boolean
    isAdminAdmin: boolean
    isBillingAdmin: boolean
    isAnalyticsAdmin: boolean
    isCustomizationAdmin: boolean
    isManageDataAdmin: boolean
    isCommentModeratorAdmin: boolean
    isAPIAdmin: boolean
    moderatorIds: string[]
    locale: FastCommentsLocale
    digestEmailFrequency: UserDigestEmailFrequency
    lastLoginDate: string
    displayLabel?: string
    karma?: number
}

GET /api/v1/tenant-users/:id

Resource: TenantUser as GET /api/v1/tenant-users/:id Credit Cost: 1

Denne rute returnerer en enkelt TenantUser efter id.

TenantUser Efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantUser Anmodningsstruktur

Copy

interface TenantUserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Svarstruktur

Copy

interface TenantUserByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
    tenantUser?: TenantUser
}

GET /api/v1/tenant-users

Resource: TenantUser as GET /api/v1/tenant-users Credit Cost: 1

Dette API bruger paginering, leveret af skip-forespørgselsparameteren. TenantUsers returneres i sider af 100, sorteret efter signUpDate, username og id.

Omkostningen er baseret på antallet af returnerede tenant-brugere og koster 1 kredit pr. 10 returnerede tenant-brugere.

TenantUser cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/tenant-users?tenantId=demo&page=0&API_KEY=DEMO_API_SECRET'

TenantUser Anmodningsstruktur

Copy

interface TenantUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** The number of tenant users to skip for pagination. **/
    skip?: number
}

TenantUser Svarstruktur

Copy

interface TenantUsersResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    tenantUsers?: TenantUser[]
}

POST /api/v1/tenant-users

Resource: TenantUser as POST /api/v1/tenant-users Credit Cost: 1

Denne rute giver mulighed for at tilføje en enkelt TenantUser.

Oprettelse af en TenantUser har følgende begrænsninger:

Et username er påkrævet.
En email er påkrævet.
signUpDate må ikke være i fremtiden.
locale skal være på listen over Understøttede Locales.
username skal være unikt på tværs af hele FastComments.com. Hvis dette er et problem, foreslår vi at bruge SSO i stedet.
email skal være unikt på tværs af hele FastComments.com. Hvis dette er et problem, foreslår vi at bruge SSO i stedet.
Du kan ikke oprette flere tenant-brugere end defineret under maxTenantUsers i din pakke.

Vi kan oprette en TenantUser som følger

TenantUser Oprettelse cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenants?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
    "email": "someone@someone.com"
}'

TenantUser Oprettelse Anmodningsstruktur

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Oprettelse Svarstruktur

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'username-required' | 'email-required' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'tenant-user-limit-reached'
    /** Included on failure. **/
    reason?: string
    tenantUser?: TenantUser; // We return the complete created tenant user on success.
}

Resource: TenantUser as POST /api/v1/tenant-users/:id/send-login-link Credit Cost: 10

Denne rute giver mulighed for at sende et login-link til en enkelt TenantUser.

Nyttigt ved batch-oprettelse af brugere uden at skulle instruere dem i, hvordan man logger ind på FastComments.com. Dette sender dem bare et "magic link" til login, der udløber efter 30 dage.

Følgende begrænsninger eksisterer for at sende et login-link til en TenantUser:

TenantUser skal allerede eksistere.
Du skal have adgang til at administrere den Tenant, som TenantUser tilhører.

Vi kan sende et login-link til en TenantUser som følger:

TenantUser Login-link cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz/send-login-link?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Dette sender en e-mail som Bob hos TenantName inviterer dig til at være moderator...

TenantUser Login-link Anmodningsstruktur

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Login-link Svarstruktur

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

PATCH /api/v1/tenant-users/:id

Resource: TenantUser as PATCH /api/v1/tenant-users/:id Credit Cost: 1

Denne rute giver mulighed for at opdatere en enkelt TenantUser.

Opdatering af en TenantUser har følgende begrænsninger:

signUpDate må ikke være i fremtiden.
locale skal være på listen over Understøttede Locales.
username skal være unikt på tværs af hele FastComments.com. Hvis dette er et problem, foreslår vi at bruge SSO i stedet.
email skal være unikt på tværs af hele FastComments.com. Hvis dette er et problem, foreslår vi at bruge SSO i stedet.
Du kan ikke opdatere tenantId for en bruger.

Vi kan oprette en TenantUser som følger

TenantUser Opdatering cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "Some Name",
    "email": "someone@someone.com"
}'

TenantUser Opdatering Anmodningsstruktur

Copy

interface TenantUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** When email or username is changed, you can set this to true to also update the user's comments. This will double the credit cost. **/
    updateComments: 'true' | 'false'
}

TenantUser Opdatering Svarstruktur

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'sign-up-date-in-future' | 'unsupported-locale' | 'unauthorized' | 'username-taken' | 'email-taken' | 'unauthorized' | 'no-package' | 'invalid-package' | 'tenant-user-limit-reached' | 'user-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/tenant-users/:id

Resource: TenantUser as DELETE /api/v1/tenant-users/:id Credit Cost: 5

Denne rute giver mulighed for fjernelse af en TenantUser efter id.

Sletning af brugerens kommentarer er mulig via deleteComments-forespørgselsparameteren. Bemærk at hvis dette er true:

Alle brugerens kommentarer vil blive slettet live.
Alle underordnede (nu forældreløse) kommentarer vil blive slettet eller anonymiseret baseret på hver kommentars tilknyttede sidekonfiguration. For eksempel, hvis trådsletningsmode er "anonymiser", vil svar forblive, og brugerens kommentarer vil blive anonymiseret. Dette gælder kun når commentDeleteMode er Remove (standardværdien).
creditsCost bliver 2.

Anonymiserede Kommentarer

Du kan bevare brugerens kommentarer, men blot anonymisere dem ved at sætte commentDeleteMode=1.

Hvis brugerens kommentarer anonymiseres, sættes følgende værdier til null:

- commenterName
- commenterEmail
- avatarSrc
- userId
- anonUserId
- mentions
- badges

isDeleted og isDeletedUser sættes til true.

Eksempler

TenantUser Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/tenant-users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

TenantUser Fjernelse Anmodningsstruktur

Copy

enum TenantUserCommentDeleteMode {
    Remove = 0, // default
    Anonymize = 1
}
interface TenantUserDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** You can set this to true to also delete the user's comments. This will double the credit cost. **/
    deleteComments?: 'true' | 'false'
    /** You can set this as desired to determine how to handle the user's comments. **/
    commentDeleteMode?: TenantUserCommentDeleteMode
}

TenantUser Fjernelse Svarstruktur

Copy

interface TenantUserDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
}

Brugerstruktur

User er et objekt, der repræsenterer en mest-almindelig-fællesnævner for alle brugere.

Husk at hos FastComments har vi en masse forskellige anvendelsestilfælde for brugere:

Sikker SSO
Simpel SSO
Tenant-brugere (For eksempel: Administratorer)
Kommentatorer

Dette API er til Kommentatorer og brugere oprettet via Simpel SSO. Grundlæggende kan enhver bruger oprettet gennem din side tilgås via dette API. Tenant-brugere kan også hentes på denne måde, men du får mere information ved at interagere med /tenant-users/ API'et.

For Sikker SSO brug venligst /sso-users/ API'et.

Du kan ikke opdatere disse typer brugere. De oprettede deres konto gennem din side, så vi giver nogle grundlæggende skrivebeskyttet adgang, men du kan ikke foretage ændringer. Hvis du vil have denne type flow - skal du opsætte Sikker SSO.

Strukturen for User-objektet er som følger:

User Struktur

Copy

export interface User {
    /** This is also the id used as userId on comment objects. **/
    id: string
    username: string
    /** A link to the commenter's blog, for example. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    avatarSrc?: string
    locale: FastCommentsLocale
    displayLabel?: string
    karma?: number
}

GET /api/v1/users/:id

Resource: User as GET /api/v1/users/:id Credit Cost: 1

Denne rute returnerer en enkelt User efter id.

User Efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/users/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

User Anmodningsstruktur

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

User Svarstruktur

Copy

interface UserByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'unauthorized'
    /** Included on failure. **/
    reason?: string
    user?: User
}

Stemmestruktur

Et Vote-objekt repræsenterer en stemme afgivet af en bruger.

Forholdet mellem kommentarer og stemme defineres via commentId.

Strukturen for Vote-objektet er som følger:

Vote Struktur

Copy

interface Vote {
    id: string
    urlId: string
    commentId: string
    userId: string
    direction: 1 | -1
    createdAt: string
}

GET /api/v1/votes

Resource: Vote as GET /api/v1/votes Credit Cost: 10

Stemmer skal hentes via urlId.

Typer af Stemmer

Der er tre typer stemmer:

Autentificerede Stemmer, som anvendes på den tilsvarende kommentar. Du kan oprette disse via dette API.
Autentificerede Stemmer, som afventer verifikation, og derfor endnu ikke er anvendt på kommentaren. Disse oprettes, når en bruger bruger FastComments.com's log ind for at stemme-mekanisme.
Anonyme Stemmer, som anvendes på den tilsvarende kommentar. Disse oprettes sammen med anonym kommentering.

Disse returneres i separate lister i API'et for at reducere forvirring.

Votes cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test'

Votes Anmodningsstruktur

Copy

interface VotesRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
}

Votes Svarstruktur

Copy

interface VotesResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Included on failure. **/
    reason?: string
    /** Authorized, verified votes, applied to their corresponding comments. **/
    appliedAuthorizedVotes: Vote[]
    /** Anonymous votes, applied to their corresponding comments. **/
    appliedAnonymousVotes: Vote[]
    /** Votes pending verification, not yet applied to their corresponding comments. **/
    pendingVotes: Vote[]
}

Bemærkninger om Anonyme Stemmer

Bemærk at anonyme stemmer oprettet via dette API vil fremgå i appliedAuthorizedVotes-listen. De betragtes som autoriserede, da de blev oprettet via API'et med en API-nøgle.

appliedAnonymousVotes-strukturen er til stemmer oprettet uden en e-mail, API-nøgle osv.

GET /api/v1/votes/for-user

Resource: Vote as GET /api/v1/votes/for-user Credit Cost: 1

Giver mulighed for at hente stemmer afgivet af en bruger på et givent urlId. Tager et userId, som kan være enhver FastComments.com eller SSO User.

Dette er nyttigt, hvis du vil vise, om en bruger har stemt på en kommentar. Når du henter kommentarer, skal du blot kalde dette API på samme tid for brugeren med det samme urlId.

Hvis du bruger anonym stemmeafgivelse, skal du i stedet sende anonUserId.

Votes For Bruger cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&userId=some-user-id'

Votes For Anon Bruger cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/votes/for-user?tenantId=demo&API_KEY=DEMO_API_SECRET&urlId=test&anonUserId=some-user-id'

Bemærk at anonyme stemmer vil fremgå i appliedAuthorizedVotes-listen. De betragtes som autoriserede, da de blev oprettet via API'et med en API-nøgle.

Votes For Bruger Anmodningsstruktur

Copy

interface VotesForUserRequestQueryParams {
    tenantId: string
    API_KEY: string
    urlId: string
    userId?: string
    anonUserId?: string
}

Votes For Bruger Svarstruktur

Copy

interface VotesForUserResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'invalid-user-id'
    /** Included on failure. **/
    reason?: string
    /** Authorized, verified votes, applied to their corresponding comments. **/
    appliedAuthorizedVotes: Vote[]
    /** Votes pending verification, not yet applied to their corresponding comments. **/
    pendingVotes: Vote[]
}

POST /api/v1/votes

Resource: Vote as POST /api/v1/votes Credit Cost: 1

Denne rute giver mulighed for at tilføje en enkelt autoriseret Vote. Stemmer kan være up (+1) eller down (-1).

Vote Oprettelse cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&userId=user-id&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

Anonym Vote Oprettelse cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/votes?tenantId=demo&API_KEY=DEMO_API_SECRET&anonUserId=some-randomly-generated-identifier&commentId=comment-id&direction=up' \
  --header 'Content-Type: application/json'

Vote Oprettelse Anmodningsstruktur

Copy

interface VotePostQueryParams {
    tenantId: string
    API_KEY: string
    userId?: string
    anonUserId?: string
    commentId: string
    direction: 'up' | 'down'
}

Vote Oprettelse Svarstruktur

Copy

interface VotePostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-user-id' | 'invalid-user-id' | 'invalid-comment-id' | 'invalid-direction' | 'duplicate' | 'voting-disabled'
    /** Included on failure. **/
    reason?: string
    voteId?: string
}

Oprettelse af Anonyme Stemmer

Anonyme stemmer kan oprettes ved at sætte anonUserId i forespørgselsparametrene i stedet for userId.

Dette id behøver ikke at svare til et brugerobjekt nogen steder (deraf anonymt). Det er simpelthen en identifikator for sessionen, så du kan hente stemmer igen i samme session for at tjekke, om der er stemt på en kommentar.

Hvis du ikke har noget som "anonyme sessioner" som FastComments har - kan du blot sætte dette til et tilfældigt ID, som en UUID (selvom vi sætter pris på mindre identifikatorer for at spare plads).

Andre Bemærkninger

Dette API overholder tenant-niveau indstillinger. For eksempel, hvis du deaktiverer afstemning for en given side, og du forsøger at oprette en stemme via API'et, vil det fejle med fejlkode voting-disabled.
Dette API er live som standard.
Dette API vil opdatere votes for den tilsvarende Comment.

DELETE /api/v1/votes/:id

Resource: Vote as DELETE /api/v1/votes/:id Credit Cost: 1

Denne rute giver mulighed for at slette en enkelt Vote.

Vote Sletning cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/votes/some-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json'

Vote Sletning Anmodningsstruktur

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Vote Sletning Svarstruktur

Copy

interface VoteDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id'
    /** Included on failure. **/
    reason?: string
}

Bemærkninger:

Dette API overholder tenant-niveau indstillinger. For eksempel, hvis du deaktiverer afstemning for en given side, og du forsøger at oprette en stemme via API'et, vil det fejle med fejlkode voting-disabled.
Dette API er live som standard.
Dette API vil opdatere votes for den tilsvarende Comment.

Domænekonfigurationsstruktur

Et DomainConfig-objekt repræsenterer konfiguration for et domæne for en tenant.

Strukturen for DomainConfig-objektet er som følger:

Domain Config Struktur

Copy

interface DomainConfig {
    /** A domain, not a URL, like "fastcomments.com" or "www.example.com". Subdomain may be included if limiting to a subdomain is desired. Max 1000 characters. **/
    domain: string
    /** The From-Name used when sending emails. **/
    emailFromName?: string
    /** The From-Email used when sending emails. Ensure SPF is setup to allow mail.fastcomments.com to send emails as the domain used in this attribute. **/
    emailFromEmail?: string
    /** READONLY. When the object was created. **/
    createdAt: string
    /** The logo related to this domain. Used in emails. Use HTTPS. **/
    logoSrc?: string
    /** A smaller logo related to this domain. Use HTTPS. **/
    logoSrc100px?: string
    /** SSO ONLY. The URL used in the footer of every email sent. Supports a "[userId]" variable. **/
    footerUnsubscribeURL?: string
    /** SSO ONLY. The headers used in of every email sent. Useful for example for setting unsubscribe related headers to improve delivery. The List-Unsubscribe entry in this Record, if it exists, supports a "[userId]" variable. **/
    emailHeaders?: Record<string, string>
    /** Disable all unsubscribe links. Not recommended, may hurt delivery rates. **/
    disableUnsubscribeLinks?: boolean
    /** DKIM Configuration. **/
    dkim?: DomainConfigDKIM
}

DKIM Config Struktur

Copy

interface DomainConfigDKIM {
    /** The domain name in your DKIM record. **/
    domainName: string
    /** The DKIM key selector to use. **/
    keySelector: string
    /** Your private key. Start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY----- **/
    privateKey: string
}

Til Autentificering

Domænekonfiguration bruges til at bestemme, hvilke websteder der kan hoste FastComments-widget'en for din konto. Dette er en grundlæggende form for autentificering, hvilket betyder, at tilføjelse eller fjernelse af domænekonfigurationer kan påvirke tilgængeligheden af din FastComments-installation i produktion.

Fjern eller opdater ikke domain-egenskaben for en Domain Config for et domæne, der i øjeblikket er i brug, medmindre deaktivering af det domæne er tilsigtet.

Dette har samme adfærd som at fjerne et domæne fra /auth/my-account/configure-domains.

Bemærk også, at fjernelse af et domæne fra Mine Domæner-brugergrænsefladen vil fjerne enhver tilsvarende konfiguration for det domæne, der måtte være blevet tilføjet via denne brugergrænseflade.

Til E-mail-tilpasning

Afmeldingslinket i e-mail-sidefoden og et-klik-afmelding-funktionen, der tilbydes af mange e-mail-klienter, kan konfigureres via denne API ved at definere henholdsvis footerUnsubscribeURL og emailHeaders.

Til DKIM

Efter at have defineret dine DKIM DNS-poster, skal du blot opdatere DomainConfig med din DKIM-konfiguration ved hjælp af den definerede struktur.

GET /api/v1/domain-configs

Resource: Comment as GET /api/v1/domain-configs Credit Cost: 1

Denne API giver mulighed for at hente alle DomainConfig-objekter for en tenant.

DomainConfig GET cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'

DomainConfig GET Anmodningsstruktur

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig GET Svarstruktur

Copy

interface GetDomainConfigsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    /** The configurations! **/
    configurations: DomainConfig[] | null
}

GET /api/v1/domain-configs/:domain

Resource: DomainConfig as GET /api/v1/domain-configs/:domain Credit Cost: 1

Individuelle DomainConfigs kan hentes via deres tilsvarende domain.

Domain Config efter Domæne cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

Domain Config efter Domæne Anmodningsstruktur

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Domain Config efter Domæne Svarstruktur

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'internal' | 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'missing-domain' | 'update-would-create-duplicate' | 'domain-does-not-exist'
    /** Included on failure. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

Resource: DomainConfig as POST /api/v1/domain-configs Credit Cost: 1

Denne API-endpoint giver mulighed for at oprette domænekonfigurationer.

Tilføjelse af konfiguration for et domæne autoriserer det domæne til FastComments-kontoen.

Almindelige anvendelser af denne API er indledende opsætning, hvis mange domæner ønskes tilføjet, eller tilpasset konfiguration til afsendelse af e-mails.

DomainConfig POST cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/domain-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "example.com",
    "emailFromName": "some from name",
    "emailFromEmail": "some@test.com",
    "logoSrc": "https://example.com/my-logo-big.png",
    "logoSrc100px": "https://example.com/my-logo-100px.png",
    "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
    "emailHeaders": {
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
        "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
    }
}'

DomainConfig POST Anmodningsstruktur

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig POST Svarstruktur

Copy

interface DomainConfigPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'configuration-exists-for-domain' | 'domain-too-long' | 'domain-invalid';
    /** Included on failure. **/
    reason?: string
    /** The created configuration. **/
    configuration?: DomainConfig
}

PATCH /api/v1/domain-configs/:domain

Resource: DomainConfig as PATCH /api/v1/domain-configs/:domain Credit Cost: 1

Denne API-endpoint giver mulighed for at opdatere en domænekonfiguration ved kun at angive domænet og attributten, der skal opdateres.

DomainConfig PATCH cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "emailFromName": "Some New From Name",
}'

DomainConfig PATCH Anmodningsstruktur

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PATCH Svarstruktur

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

PUT /api/v1/domain-configs/:domain

Resource: DomainConfig as PUT /api/v1/domain-configs/:domain Credit Cost: 1

Denne API-endpoint giver mulighed for at erstatte en domænekonfiguration.

DomainConfig PUT cURL Eksempel

Copy

curl --request PUT \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "domain": "new-domain-example.com",
    "emailFromName": "some from name",
    "emailFromEmail": "some@test.com",
    "logoSrc": "https://example.com/my-logo-big.png",
    "logoSrc100px": "https://example.com/my-logo-100px.png",
    "footerUnsubscribeURL": "http://example.com/unsubscribe-ui",
    "emailHeaders": {
        "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
        "List-Unsubscribe": "<https://example.com/opt-out/[userId]>"
    }
}'

DomainConfig PUT Anmodningsstruktur

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PUT Svarstruktur

Copy

interface DomainConfigPutResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input' | 'missing-domain' | 'domain-does-not-exist' | 'update-would-create-duplicate' | 'domain-too-long' | 'domain-invalid';
    /** Included on failure. **/
    reason?: string
    /** The updated configuration. **/
    configuration?: DomainConfig
}

DELETE /api/v1/domain-configs/:domain

Resource: DomainConfig as DELETE /api/v1/domain-configs/:domain Credit Cost: 1

Denne rute giver mulighed for at fjerne en enkelt DomainConfig efter id.

Bemærk: Fjernelse af en DomainConfig vil afautorisere det domæne fra at bruge FastComments.
Bemærk: Gentilføjelse af et domæne via brugergrænsefladen vil genskabe objektet (med kun domain udfyldt).

DomainConfig Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/domain-configs/example.com?tenantId=demo&API_KEY=DEMO_API_SECRET'

DomainConfig Fjernelse Anmodningsstruktur

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig Fjernelse Svarstruktur

Copy

interface DomainConfigDeleteResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-domain' | 'domain-config-does-not-exist'
    /** Included on failure. **/
    reason?: string
}

Spørgsmålskonfigurationsstruktur

FastComments giver en måde at konstruere spørgsmål og aggregere deres resultater. Et eksempel på et spørgsmål (herefter kaldet QuestionConfig) kunne være en stjernebedømmelse, en skyder eller et NPS-spørgsmål (bestemt via type).

Spørgsmålsdata kan aggregeres individuelt, sammen, over tid, samlet, efter side og så videre.

Frameworket har alle de nødvendige funktioner til at bygge klientside-widgets (med din server foran dette API), admin-dashboards og rapporteringsværktøjer.

Først skal vi definere en QuestionConfig. Strukturen er som følger:

QuestionConfig Struktur

Copy

type QuestionConfigType = 'nps' | 'slider' | 'star' | 'thumbs';
interface QuestionConfig {
    id: string
    tenantId: string
    name: string
    question: string
    helpText?: string
    createdAt: string
    createdBy: string
    /** READONLY - incremented for each new response. **/
    usedCount: number
    /** A date string for when the configuration was last used (result left). **/
    lastUsed?: string
    type: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder: number
}

GET /api/v1/question-configs

Resource: QuestionConfig as GET /api/v1/question-configs Credit Cost: 1

Denne rute returnerer op til 100 QuestionConfig-objekter ad gangen, pagineret. Prisen er 1 pr. hver 100 objekter. De er sorteret efter spørgsmålstekst stigende (question-felt).

QuestionConfig Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionConfig Anmodningsstruktur

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
    /** For pagination. Starts at 0. **/
    skip?: number
}

QuestionConfig Svarstruktur

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    questionConfigs: QuestionConfig[]
}

GET /api/v1/question-configs/:id

Resource: QuestionConfig as GET /api/v1/question-configs/:id Credit Cost: 1

Denne rute returnerer en enkelt QuestionConfig efter dens id.

QuestionConfig Efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionConfig Anmodningsstruktur

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig Svarstruktur

Copy

interface QuestionConfigByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    questionConfig?: QuestionConfig
}

POST /api/v1/question-configs

Resource: QuestionConfig as POST /api/v1/question-configs Credit Cost: 1

Denne API-endpoint giver mulighed for at oprette en QuestionConfig.

QuestionConfig POST cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-configs?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Some name that shows on reports.",
    "question": "how much do you like this api?",
    "type": 'slider',
    "reportingOrder": 0,
    "min": 0,
    "max": 10
}'

QuestionConfig POST Anmodningsstruktur

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig POST Svarstruktur

Copy

interface QuestionConfigPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
    /** Included on failure. **/
    reason?: string
    /** The created object. **/
    questionConfig?: QuestionConfig
}

PATCH /api/v1/question-configs/:id

Resource: QuestionConfig as PATCH /api/v1/question-configs/:id Credit Cost: 1

Denne rute giver mulighed for at opdatere en enkelt QuestionConfig.

Følgende struktur repræsenterer alle værdier, der kan ændres:

QuestionConfig Struktur

Copy

interface QuestionConfigPatchBody {
    name?: string
    question?: string
    helpText?: string
    /** Beware! Changing type may throw off reporting if min/max is different. **/
    type?: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder?: number
}

QuestionConfig Opdatering cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/question-configs/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "question": "some new question text"
}'

QuestionConfig Opdatering Anmodningsstruktur

Copy

interface QuestionConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig Opdatering Svarstruktur

Copy

interface QuestionConfigPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/question-configs/:id

Resource: QuestionConfig as DELETE /api/v1/question-configs/:id Credit Cost: 100

Denne rute giver mulighed for at fjerne en QuestionConfig efter id.

Dette vil slette alle tilsvarende spørgsmålsresultater (men ikke kommentarerne). Dette er en del af den høje kreditomkostning.

QuestionConfig Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/question-configs/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionConfig Fjernelse Anmodningsstruktur

Copy

interface QuestionConfigDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig Fjernelse Svarstruktur

Copy

interface QuestionConfigResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

Spørgsmålresultatstruktur

For at gemme resultater for spørgsmål opretter du et QuestionResult. Du kan derefter aggregere spørgsmålsresultater og også knytte dem til kommentarer til rapporteringsformål.

QuestionResult Struktur

Copy

interface QuestionResultMeta {
    name: string
    values: string[]
}
interface QuestionResult {
    id: string
    tenantId: string
    urlId: string
    anonUserId?: string
    userId?: string
    createdAt?: string
    value: number
    commentId?: string
    questionId: string
    meta?: QuestionResultMeta[]
}

GET /api/v1/question-results

Resource: QuestionResults as GET /api/v1/question-results Credit Cost: 1

Denne rute returnerer op til 1000 QuestionResults-objekter ad gangen, pagineret. Prisen er 1 pr. hver 100 objekter. De er sorteret efter createdAt, stigende. Du kan filtrere efter forskellige parametre.

QuestionResults Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionResults Anmodningsstruktur

Copy

interface QuestionResultsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** For pagination. Starts at 0. **/
    skip?: number
    /** For pagination. **/
    limit?: number
    /** Get the results from a specific page. **/
    urlId?: string
    /** Get the results from a specific user. **/
    userId?: string
    startDate?: string | number
    questionId?: string | string[]
}

QuestionResults Svarstruktur

Copy

interface QuestionResultsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    questionResults: QuestionResults[]
}

GET /api/v1/question-results/:id

Resource: QuestionResult as GET /api/v1/question-results/:id Credit Cost: 1

Denne rute returnerer et enkelt QuestionResult efter dets id.

QuestionResult Efter ID cURL Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionResult Anmodningsstruktur

Copy

interface QuestionResultRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult Svarstruktur

Copy

interface QuestionResultByIdResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
    questionResult?: QuestionResult
}

POST /api/v1/question-results

Resource: QuestionResult as POST /api/v1/question-results Credit Cost: 1

Denne API-endpoint giver mulighed for at oprette et QuestionResult.

QuestionResult POST cURL Eksempel

Copy

curl --request POST \
  --url 'https://fastcomments.com/api/v1/question-results?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "urlId": "some-page-id",
    "anonUserId": 'anon-0',
    "userId": 'user-0',
    "value": 10,
    "questionId": "some-question-id",
    "meta": [
        {
            name: "example",
            values: ["value-1", "value-2"]
        }
    ]
}'

QuestionResult POST Anmodningsstruktur

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult POST Svarstruktur

Copy

interface QuestionResultPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';
    /** Included on failure. **/
    reason?: string
    /** The created object. **/
    questionResult?: QuestionResult
}

PATCH /api/v1/question-results/:id

Resource: QuestionResult as PATCH /api/v1/question-results/:id Credit Cost: 1

Denne rute giver mulighed for at opdatere et enkelt QuestionResult.

Følgende struktur repræsenterer alle værdier, der kan ændres:

QuestionResult Struktur

Copy

interface QuestionResultPatchBody {
    urlId?: string
    anonUserId?: string
    userId?: string
    value?: string
    commentId?: string
    questionId?: string
    meta?: QuestionResultMeta[]
}

QuestionResult Opdatering cURL Eksempel

Copy

curl --request PATCH \
  --url 'https://fastcomments.com/api/v1/question-results/my-id?tenantId=demo&API_KEY=DEMO_API_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "value": 5
}'

QuestionResult Opdatering Anmodningsstruktur

Copy

interface QuestionResultPatchQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult Opdatering Svarstruktur

Copy

interface QuestionResultPatchResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'unauthorized' | 'missing-api-key' | 'missing-id' | 'not-found' | 'empty-request' | 'invalid-input'
    /** Included on failure. **/
    reason?: string
}

DELETE /api/v1/question-results/:id

Resource: QuestionResult as DELETE /api/v1/question-results/:id Credit Cost: 1

Denne rute giver mulighed for at fjerne et QuestionResult efter id.

QuestionResult Fjernelse cURL Eksempel

Copy

curl --request DELETE \
  --url 'https://fastcomments.com/api/v1/question-results/xyz?tenantId=demo&API_KEY=DEMO_API_SECRET'

QuestionResult Fjernelse Anmodningsstruktur

Copy

interface QuestionResultDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult Fjernelse Svarstruktur

Copy

interface QuestionResultResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found'
    /** Included on failure. **/
    reason?: string
}

GET /api/v1/question-results-aggregate

Resource: QuestionResultsAggregate as GET /api/v1/question-results-aggregate Credit Cost: 2

Her sker aggregering af resultater.

Aggregerings-svarstrukturen er som følger:

QuestionResultsAggregationResult Struktur

Copy

interface QuestionResultDataPoint {
    /** A map of value to count of occurrences of that value for the current data point (date bucket or page). **/
    v: Map<ValueAsString, number>
    total: number
}
interface QuestionResultsAggregationResult {
    /** Note - is null when timeBucket not specified. **/
    dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
    dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
    countsByValue?: Map<ValueAsString, number>
    /** The total number of results aggregated. **/
    total: number
    /** The resulting weighted average. It is a float, usually two decimals or fewer. **/
    average: number
    /** A date string representing when this data was calculated, since it might come from cache. **/
    createdAt: string
}

Her er query-parametrene tilgængelige for aggregering:

QuestionResultsAggregation Anmodningsstruktur

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** You can aggregate results for one or more questions. **/
    questionId: string | string[]
    startDate?: string | number
    timeBucket?: 'day' | 'month' | 'year'
    /** Aggregate for a specific page. **/
    urlId?: string
    /** Aggregate for a specific user. **/
    userId?: string
    /** Force recalculate now and update the cache. **/
    forceRecalculate?: boolean
}

Her er et eksempel på en anmodning:

QuestionResultsAggregation Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id'

Eksempel på svar:

QuestionResultsAggregation Svar Eksempel

Copy

    {
        "average": 8.33,
        "countsByValue": {
            "5": 1,
            "10": 2
        },
        "createdAt": "2023-08-30T00:00:00.000Z",
        "dataByUrlId": {
            "some-page": {
                "total": 3,
                "v": {
                    "5": 1,
                    "10": 2
                }
            }
        },
        "total": 3
    }

QuestionResultsAggregation Svarstruktur

Copy

interface QuestionResultsAggregationResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    data: QuestionResultsAggregationResult
}

Ydelsesbemærkninger

For en cache-miss tager aggregeringer generelt fem sekunder pr. million resultater.
Ellers er anmodninger konstant-tid.

Caching og Omkostningsbemærkninger

Når forceRecalculate er angivet, er omkostningen altid 10 i stedet for de normale 2.
Hvis cachen udløber og data genberegnes, er omkostningen stadig en konstant 2, hvis forceRecalculate ikke er angivet. Cachen udløber baseret på datasættets størrelse, der aggregeres (kan variere mellem 30 sekunder og 5 minutter).
Dette er for at tilskynde brug af cachen.

GET /api/v1/question-results-aggregate/combine/comments

Resource: QuestionResultsCombinedWithComments as GET /api/v1/question-results-aggregate/combine/comments Credit Cost: 2

Her sker kombination af resultater med kommentarer. Nyttigt til at oprette et "nylige positive og negative kommentarer" diagram for et produkt, for eksempel.

Du kan søge via et interval af værdier (inklusiv), et eller flere spørgsmål og efter en startdato (inklusiv).

Svarstrukturen er som følger:

QuestionResultsCombinedWithCommentsResponse Struktur

Copy

interface SimpleComment {
    id: string
    commenterName: string
    userId?: string
    date: string
    commentHTML: string
}
interface SimpleQuestionResult {
    id: string
    value: number
}
interface CommentAndResult {
    comment: SimpleComment
    result: SimpleQuestionResult
}
interface QuestionResultsCombinedWithCommentsResponse {
    /** A date string representing when this data was calculated, since it might come from cache. **/
    createdAt: string
    results: CommentAndResult[]
}

Her er query-parametrene tilgængelige for aggregering:

QuestionResultsCombineComments Anmodningsstruktur

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** You can aggregate results for one or more questions. **/
    questionId: string | string[]
    startDate?: string | number
    urlId?: string
    minValue: number
    maxValue: number
    limit?: number
    forceRecalculate?: boolean
}

Her er et eksempel på en anmodning:

QuestionResultsCombineComments Eksempel

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/question-results-aggregation/combine/comments?tenantId=demo&API_KEY=DEMO_API_SECRET&questionId=some-question-id&minValue=5&maxValue=10'

Eksempel på svar:

QuestionResultsCombineComments Svar Eksempel

Copy

{
    "createdAt": "2023-08-30T00:00:00.000Z",
    "results": [
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-2",
                "commenterName": "Test",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 10
            }
        },
        {
            "comment": {
                "id": "some-id",
                "commentHTML": "test-0",
                "commenterName": "Some Name",
                "date": "2023-08-30T00:00:00.000Z",
                "userId": "some-user-id"
            },
            "result": {
                "id": "some-id",
                "value": 5
            }
        }
    ]
}

QuestionResultsCombineComments Svarstruktur

Copy

interface QuestionResultsCombineCommentsResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Included on failure. **/
    reason?: string
    data: QuestionResultsCombinedWithCommentsResponse
}

Caching og Omkostningsbemærkninger

Når forceRecalculate er angivet, er omkostningen altid 10 i stedet for de normale 2.
Hvis cachen udløber og data genberegnes, er omkostningen stadig en konstant 2, hvis forceRecalculate ikke er angivet.
Dette er for at tilskynde brug af cachen.

Brugerbadge-struktur

UserBadge er et objekt, der repræsenterer et badge tildelt til en bruger i FastComments-systemet.

Badges kan tildeles brugere automatisk baseret på deres aktivitet (såsom kommentarantal, svartid, veteranstatus) eller manuelt af side-administratorer.

Strukturen for UserBadge-objektet er som følger:

UserBadge Struktur

Copy

export interface UserBadge {
    /** Unique identifier for this user badge assignment */
    id: string
    /** ID of the user this badge is assigned to */
    userId: string
    /** ID of the badge definition from the tenant's badge catalog */
    badgeId: string
    /** ID of the tenant that created/assigned this badge */
    fromTenantId: string
    /** When this badge was created (milliseconds since epoch) */
    createdAt?: number
    /** When this badge was received by the user (milliseconds since epoch) */
    receivedAt?: number
    /**
     * The badge type:
     * 0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, 3=CommentsPinned,
     * 4=Veteran, 5=NightOwl, 6=FastReplyTime, 7=ModeratorCommentsDeleted,
     * 8=ModeratorCommentsApproved, 9=ModeratorCommentsUnapproved, 10=ModeratorCommentsReviewed,
     * 11=ModeratorCommentsMarkedSpam, 12=ModeratorCommentsMarkedNotSpam, 13=RepliedToSpecificPage,
     * 14=Manual
     */
    type: number
    /** For threshold-based badges, the threshold value */
    threshold?: number
    /** The name/label of the badge */
    name?: string
    /** Detailed description of the badge */
    description?: string
    /** The text shown on the badge */
    displayLabel?: string
    /** URL to an image shown on the badge */
    displaySrc?: string
    /** Background color for the badge (hex code) */
    backgroundColor?: string
    /** Border color for the badge (hex code) */
    borderColor?: string
    /** Text color for the badge (hex code) */
    textColor?: string
    /** Additional CSS class for styling */
    cssClass?: string
    /** For veteran badges, the time threshold in milliseconds */
    veteranUserThresholdMillis?: number
    /** Whether this badge is displayed on the user's comments */
    displayedOnComments: boolean
    /** The display order of the badge */
    order?: number
}

GET /api/v1/user-badges

Dette endpoint giver dig mulighed for at hente bruger-badges baseret på forskellige kriterier.

Eksempel på Anmodning:

GET Anmodningseksempel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET"

Du kan tilføje forskellige forespørgselsparametre for at filtrere resultaterne:

userId - Hent badges for en specifik bruger
badgeId - Hent forekomster af et specifikt badge
type - Filtrer efter badge-type (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, osv. Se UserBadge-strukturen for fuld liste)
displayedOnComments - Filtrer efter om badge'et vises på kommentarer (true/false)
limit - Maksimalt antal badges at returnere (standard 30, maks 200)
skip - Antal badges at springe over (til paginering)

Eksempel på Svar:

Svar

Copy

{
  "status": "success",
  "userBadges": [
    {
      "id": "badge123",
      "userId": "user456",
      "badgeId": "badgeDef789",
      "fromTenantId": "tenant001",
      "createdAt": 1650532511000,
      "receivedAt": 1650532511000,
      "type": 14,
      "name": "Special Contributor",
      "description": "Awarded to special contributors to our community",
      "displayLabel": "Special",
      "backgroundColor": "#4a5568",
      "textColor": "#ffffff",
      "displayedOnComments": true,
      "order": 1
    },
    {
      "id": "badge124",
      "userId": "user456",
      "badgeId": "badgeDef790",
      "fromTenantId": "tenant001",
      "createdAt": 1650532598000,
      "receivedAt": 1650532598000,
      "type": 0,
      "threshold": 100,
      "name": "Centurion",
      "description": "Made 100 comments",
      "displayLabel": "100",
      "backgroundColor": "#2b6cb0",
      "textColor": "#ffffff",
      "displayedOnComments": true,
      "order": 2
    }
  ]
}

Mulige Fejlsvar:

Fejl: Manglende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fejl: Ugyldig Grænse

Copy

{
  "status": "failed",
  "code": "invalid-limit",
  "reason": "The limit (query param: limit) is too large (> 200)."
}

GET /api/v1/user-badges/:id

Dette endpoint giver dig mulighed for at hente et specifikt bruger-badge efter dets unikke ID.

Eksempel på Anmodning:

GET Anmodningseksempel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Eksempel på Svar:

Svar

Copy

{
  "status": "success",
  "userBadge": {
    "id": "badge123",
    "userId": "user456",
    "badgeId": "badgeDef789",
    "fromTenantId": "tenant001",
    "createdAt": 1650532511000,
    "receivedAt": 1650532511000,
    "type": 14,
    "name": "Special Contributor",
    "description": "Awarded to special contributors to our community",
    "displayLabel": "Special",
    "backgroundColor": "#4a5568",
    "textColor": "#ffffff",
    "displayedOnComments": true,
    "order": 1
  }
}

Mulige Fejlsvar:

Fejl: Manglende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fejl: Ikke Fundet

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

POST /api/v1/user-badges

Dette endpoint giver dig mulighed for at oprette en ny bruger-badge tildeling.

Eksempel på Anmodning:

POST Anmodningseksempel

Copy

Run

curl -X POST "https://fastcomments.com/api/v1/user-badges?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "userId": "user456",
  "badgeId": "badgeDef789",
  "displayedOnComments": true
}'

Anmodningskroppen skal indeholde følgende parametre:

userId (påkrævet) - ID'et for brugeren, der skal tildeles badge'et
badgeId (påkrævet) - ID'et for badge'et, der skal tildeles
displayedOnComments (valgfrit) - Om badge'et skal vises på brugerens kommentarer (standard er true)

Vigtige Bemærkninger:

Badge'et skal eksistere og være aktiveret i din tenants badge-katalog
Du kan kun tildele badges til brugere, der tilhører din tenant eller har kommenteret på din side

Eksempel på Svar:

Svar

Copy

{
  "status": "success",
  "userBadge": {
    "id": "badge123",
    "userId": "user456",
    "badgeId": "badgeDef789",
    "fromTenantId": "tenant001",
    "createdAt": 1650532511000,
    "receivedAt": 1650532511000,
    "type": 14,
    "name": "Special Contributor",
    "description": "Awarded to special contributors to our community",
    "displayLabel": "Special",
    "backgroundColor": "#4a5568",
    "textColor": "#ffffff",
    "displayedOnComments": true,
    "order": 1
  }
}

Mulige Fejlsvar:

Fejl: Manglende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fejl: Manglende Bruger ID

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "User ID (body param: userId) is required."
}

Fejl: Manglende Badge ID

Copy

{
  "status": "failed",
  "code": "missing-badge-id",
  "reason": "Badge ID (body param: badgeId) is required."
}

Fejl: Badge Ikke Fundet

Copy

{
  "status": "failed",
  "code": "badge-not-found",
  "reason": "The badge badgeDef789 was not found or is not enabled."
}

Fejl: Uautoriseret Bruger

Copy

{
  "status": "failed",
  "code": "unauthorized-user",
  "reason": "You can only add badges to users who belong to your tenant or have commented on your site."
}

PUT /api/v1/user-badges/:id

Dette endpoint giver dig mulighed for at opdatere en bruger-badge tildeling.

I øjeblikket er den eneste egenskab, der kan opdateres, displayedOnComments, som styrer, om badge'et vises på brugerens kommentarer.

Eksempel på Anmodning:

PUT Anmodningseksempel

Copy

Run

curl -X PUT "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
  "displayedOnComments": false
}'

Eksempel på Svar:

Svar

Copy

{
  "status": "success"
}

Mulige Fejlsvar:

Fejl: Manglende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fejl: Manglende ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Fejl: Ikke Fundet

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

DELETE /api/v1/user-badges/:id

Dette endpoint giver dig mulighed for at slette en bruger-badge tildeling.

Eksempel på Anmodning:

DELETE Anmodningseksempel

Copy

Run

curl -X DELETE "https://fastcomments.com/api/v1/user-badges/badge123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Eksempel på Svar:

Svar

Copy

{
  "status": "success"
}

Mulige Fejlsvar:

Fejl: Manglende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fejl: Manglende ID

Copy

{
  "status": "failed",
  "code": "missing-id",
  "reason": "The User Badge ID (url param: id) is missing."
}

Fejl: Ikke Fundet

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge badge123 was not found."
}

Brugerbadge-fremgangsstruktur

UserBadgeProgress er et objekt, der repræsenterer en brugers fremskridt mod at optjene forskellige badges i FastComments-systemet.

Denne sporing hjælper med at bestemme, hvornår brugere skal modtage automatiske badges baseret på deres aktivitet og deltagelse i dit fællesskab.

Strukturen for UserBadgeProgress-objektet er som følger:

UserBadgeProgress Struktur

Copy

export interface UserBadgeProgress {
    /** Unique identifier for this progress record */
    id: string
    /** ID of the tenant this progress record belongs to */
    tenantId: string
    /** ID of the user this progress record tracks */
    userId: string
    /** ID of the user's first comment in the system */
    firstCommentId?: string
    /** Date of the user's first comment (milliseconds since epoch) */
    firstCommentDate?: number
    /** Automatically calculated trust factor based on user activity */
    autoTrustFactor?: number
    /** Manually set trust factor by administrators */
    manualTrustFactor?: number
    /** Detailed progress object with various metrics, keys match BadgeType enum */
    progress: {
        /** 0: CommentCount - Count of comments the user has made */
        '0'?: number
        /** 1: CommentUpVotes - Count of upvotes the user has received */
        '1'?: number
        /** 2: CommentReplies - Count of replies the user has made */
        '2'?: number
        /** 3: CommentsPinned - Count of pinned comments the user has */
        '3'?: number
        /** 4: Veteran - User's account age */
        '4'?: number
        /** 5: NightOwl - Times user has posted during nighttime hours */
        '5'?: number
        /** 6: FastReplyTime - Average reply time in milliseconds */
        '6'?: number
        /** 7: ModeratorCommentsDeleted - For moderator badges, comments deleted count */
        '7'?: number
        /** 8: ModeratorCommentsApproved - For moderator badges, comments approved count */
        '8'?: number
        /** 9: ModeratorCommentsUnapproved - For moderator badges, comments unapproved count */
        '9'?: number
        /** 10: ModeratorCommentsReviewed - For moderator badges, comments reviewed count */
        '10'?: number
        /** 11: ModeratorCommentsMarkedSpam - For moderator badges, comments marked as spam count */
        '11'?: number
        /** 12: ModeratorCommentsMarkedNotSpam - For moderator badges, comments marked as not spam count */
        '12'?: number
        /** 13: RepliedToSpecificPage - For each page, count of replies */
        '13'?: Record<string, number>
    }
}

GET /api/v1/user-badge-progress

Dette endpoint giver dig mulighed for at hente bruger-badge fremskridtsposter baseret på forskellige kriterier.

Eksempel på Anmodning:

GET Anmodningseksempel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress?tenantId=demo&API_KEY=DEMO_API_SECRET"

Du kan tilføje forskellige forespørgselsparametre for at filtrere resultaterne:

userId - Hent fremskridt for en specifik bruger
limit - Maksimalt antal poster at returnere (standard 30, maks 200)
skip - Antal poster at springe over (til paginering)

Eksempel på Svar:

Svar

Copy

{
  "status": "success",
  "userBadgeProgresses": [
    {
      "id": "progress123",
      "tenantId": "tenant001",
      "userId": "user456",
      "firstCommentId": "comment789",
      "firstCommentDate": 1650532511000,
      "autoTrustFactor": 0.75,
      "progress": {
        "0": 42,
        "1": 120,
        "2": 15,
        "3": 3,
        "5": 5,
        "6": 1800000,
        "8": 0,
        "7": 0
      }
    },
    {
      "id": "progress124",
      "tenantId": "tenant001",
      "userId": "user789",
      "firstCommentId": "comment790",
      "firstCommentDate": 1650532598000,
      "autoTrustFactor": 0.5,
      "progress": {
        "0": 12,
        "1": 15,
        "2": 4
      }
    }
  ]
}

Mulige Fejlsvar:

Fejl: Manglende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fejl: Ugyldig Grænse

Copy

{
  "status": "failed",
  "code": "invalid-limit",
  "reason": "The limit (query param: limit) is too large (> 200)."
}

GET /api/v1/user-badge-progress/:id

Dette endpoint giver dig mulighed for at hente en specifik bruger-badge fremskridtspost efter dens unikke ID.

Eksempel på Anmodning:

GET Anmodningseksempel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/progress123?tenantId=demo&API_KEY=DEMO_API_SECRET"

Eksempel på Svar:

Svar

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

Mulige Fejlsvar:

Fejl: Manglende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fejl: Ikke Fundet

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "The user badge progress progress123 was not found."
}

GET /api/v1/user-badge-progress/user/:userId

Dette endpoint giver dig mulighed for at hente en brugers badge-fremskridtspost efter deres bruger-ID.

Eksempel på Anmodning:

GET Anmodningseksempel

Copy

Run

curl -X GET "https://fastcomments.com/api/v1/user-badge-progress/user/user456?tenantId=demo&API_KEY=DEMO_API_SECRET"

Eksempel på Svar:

Svar

Copy

{
  "status": "success",
  "userBadgeProgress": {
    "id": "progress123",
    "tenantId": "tenant001",
    "userId": "user456",
    "firstCommentId": "comment789",
    "firstCommentDate": 1650532511000,
    "autoTrustFactor": 0.75,
    "progress": {
      "0": 42,
      "1": 120,
      "2": 15,
      "3": 3,
      "5": 5,
      "6": 1800000,
      "8": 0,
      "7": 0
    }
  }
}

Mulige Fejlsvar:

Fejl: Manglende Tenant ID

Copy

{
  "status": "failed",
  "code": "missing-tenant-id",
  "reason": "Tenant ID (query param: tenantId) is missing."
}

Fejl: Manglende Bruger ID

Copy

{
  "status": "failed",
  "code": "missing-user-id",
  "reason": "The User ID (path param: userId) is missing."
}

Fejl: Ikke Fundet

Copy

{
  "status": "failed",
  "code": "not-found",
  "reason": "No badge progress found for user user456 in tenant tenant001."
}

Afslutningsvis

Vi håber, at du har fundet vores API-dokumentation grundig og nem at forstå. Hvis du finder nogen mangler, så lad os det vide nedenfor.

Sprog 🇩🇰 Dansk

API-ressourcer

Aggregeringer

Auditlogs

Kommentarer

E-mail-skabeloner

Hashtags

Moderatorer

Notifikationstælling

Notifikationer

Sider

Ventende webhook-hændelser

SSO-brugere

Abonnementer

Lejers daglige forbrug

Lejere

Lejerpakker

Lejerbrugere

Brugere

Stemmer

Domænekonfigurationer

Spørgsmålskonfigurationer

Spørgsmålresultater

Aggregering af spørgsmålresultater

Brugerbadges

Brugerbadge-fremgang

FastComments API

Genererede SDK'er

Autentificering

Sikkerhedsnote

Autentificeringsmulighed Én - Headers

Autentificeringsmulighed To - Forespørgselsparametre

API-ressourcer

Aggreger dine data

Eksempler

Eksempel: Tæl unikke

Eksempel: Antal distinkte

Eksempel: Sum af værdier for flere felter

Eksempel: Gennemsnit af værdier for flere felter

Eksempel: Min/Max for flere felter

Eksempel: Tæl unikke værdier for flere felter

Eksempel: Oprettelse af forespørgsel

Eksempel: Tæl kommentarer, der venter på gennemgang

Eksempel: Opdeling af godkendte, gennemgåede og spam-kommentarer

Strukturer

Auditlog-struktur

GET /api/v1/audit-logs

Kommentarstruktur

Comment Text Structure

Tagging

HashTags

GET /api/v1/comments

Paginering

Tråde

Træer forklaret

Hentning af kommentarer i brugerkontekst

Hent kommentarer som et træ

Hent kommentarer som træ, søgning efter hashtag

Alle forespørgselsparametre

Svaret

Brugbare tips

URL-id

Anonyme handlinger

Kommentarer returneres ikke

GET /api/v1/comments/:id

POST /api/v1/comments

PATCH /api/v1/comments/:id

DELETE /api/v1/comments/:id

POST /api/v1/comments/:id/flag

POST /api/v1/comments/:id/un-flag

POST /api/v1/comments/:id/block

POST /api/v1/comments/:id/un-block

E-mail-skabelonstruktur

Bemærkninger

GET /api/v1/email-templates/:id

GET /api/v1/email-templates

PATCH /api/v1/email-templates/:id

POST /api/v1/email-templates

POST /api/v1/email-templates/render

DELETE /api/v1/email-templates/:id