API | FastComments Docs

De FastComments API

FastComments biedt een API voor het werken met veel resources. Bouw integraties met ons platform, of bouw zelfs je eigen clients!

In deze documentatie vindt u alle door de API ondersteunde resources, gedocumenteerd met hun request- en response-typen.

Voor Enterprise-klanten wordt alle API-toegang vastgelegd in het Audit Log.

Gegenereerde SDK's

FastComments genereert nu een API-specificatie uit onze code (dit is nog niet compleet, maar bevat veel API's).

We hebben nu ook SDK's voor populaire talen:

Authenticatie

De API wordt geauthenticeerd door uw API-sleutel als X-API-KEY header of API_KEY queryparameter mee te sturen. U heeft ook uw tenantId nodig om API-aanroepen te doen. Deze kan worden opgehaald vanaf dezelfde pagina als uw API-sleutel.

Beveiligingsnotitie

Deze routes zijn bedoeld om vanaf een server te worden aangeroepen. ROEP ZE NIET vanuit een browser. Als u dat doet, maakt u uw API-sleutel openbaar - dit geeft volledige toegang tot uw account aan iedereen die de broncode van een pagina kan bekijken!

Authenticatieoptie één - Headers

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

Authenticatieoptie twee - Query-parameters

Query Param: API_KEY
Query Param: tenantId

API-bronnen

Gebruik van resources

Het ophalen van gegevens van de API wordt als gebruik op uw account gerekend.

Elke resource vermeldt wat dat gebruik is in zijn eigen sectie.

Sommige resources kosten meer om te leveren dan andere. Elk endpoint heeft een vaste kosten in credits per API-aanroep. Voor sommige endpoints varieert het aantal credits op basis van de opties en de grootte van de respons.

Het API-gebruik is te controleren op de Factureringsanalyse-pagina en wordt elk paar minuten bijgewerkt.

Opmerking!

We raden aan eerst de Pages-documentatie te lezen, om verwarring te beperken bij het bepalen welke waarden je moet doorgeven voor urlId in de Comment API.

Aggregeer uw gegevens

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

Deze API aggregeert documenten door ze te groeperen (als groupBy is opgegeven) en meerdere bewerkingen toe te passen. Verschillende bewerkingen (bijv. sum, countDistinct, avg, enz.) worden ondersteund.

De kosten zijn variabel. Elke 500 gescande objecten kost 1 API-credit.

Het maximale geheugenverbruik dat standaard per API-aanroep is toegestaan is 64MB, en standaard mag u slechts één aggregatie tegelijk laten draaien. Als u meerdere aggregaties gelijktijdig indient, worden deze in de wachtrij geplaatst en uitgevoerd in de volgorde van indiening. In afwachting zijnde aggregaties wachten maximaal 60 seconden, daarna loopt het verzoek time-out. Individuele aggregaties kunnen tot 5 minuten draaien.

Als u beheerde tenants heeft, kunt u alle onderliggende tenant-resources in één aanroep aggregeren door de query-parameter parentTenantId door te geven.

Voorbeelden

Voorbeeld: Unieke waarden tellen

Voorbeeld cURL: Unieke waarden tellen

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" }
    ]
}'

Antwoord: Unieke waarden tellen

Copy

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

Voorbeeld: Aantal unieke waarden

Voorbeeld cURL: Aantal unieke waarden

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" }
    ]
}'

Antwoord:

Antwoord: Aantal unieke waarden

Copy

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

Voorbeeld: Som van waarden van meerdere velden

Voorbeeld cURL: Optellen van waarden

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" }
    ]
}'

Antwoord:

Antwoord: Som van waarden

Copy

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

Voorbeeld: Gemiddelde waarden van meerdere velden

Voorbeeld cURL: Gemiddelde waarden

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" }
    ]
}'

Antwoord:

Antwoord: Gemiddelde waarden

Copy

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

Voorbeeld: Min/Max waarden van meerdere velden

Voorbeeld cURL: Min/Max waarden

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" }
    ]
}'

Antwoord:

Antwoord: Min/Max waarden

Copy

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

Voorbeeld: Unieke waarden tellen voor meerdere velden

Voorbeeld cURL: Unieke waarden tellen

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" }
    ]
}'

Antwoord:

Antwoord: Unieke waarden tellen

Copy

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

Voorbeeld: Query aanmaken

Voorbeeld cURL: Query-aanmaak

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" }
    ]
}'

Antwoord:

Antwoord: Query-aanmaak

Copy

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

Voorbeeld: Aantal opmerkingen in afwachting van beoordeling

Voorbeeld cURL: Aantal opmerkingen in afwachting van beoordeling

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" }
    ]
}'

Antwoord:

Antwoord: Aantal opmerkingen in afwachting van beoordeling

Copy

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

Voorbeeld: Opsplitsing van goedgekeurde, beoordeelde en spam-opmerkingen

Voorbeeld cURL: Opsplitsing van opmerkingen

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" }
    ]
}'

Antwoord:

Antwoord: Opsplitsing van opmerkingen

Copy

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

Structuren

Structuur van Aggregate-aanvraag

Copy

export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
/** Een bewerking die op een veld wordt toegepast */
export interface AggregationOperation {
    /** Het veld waarop de bewerking wordt toegepast */
    field: string;
    /** Het type bewerking */
    op: AggregationOpType;
    /** Optionele alias voor de output; indien niet opgegeven wordt een standaardalias berekend */
    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
};

Structuur van Aggregate-respons

Copy

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

De volgende resources kunnen worden geaggregeerd:

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

Auditlogstructuur

Een AuditLog is een object dat een geaudit evenement vertegenwoordigt voor huurders die toegang hebben tot deze functie.

De structuur voor het AuditLog-object is als volgt:

AuditLog-structuur

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

Het auditlogboek is onveranderlijk. Het kan ook niet handmatig worden geschreven. FastComments.com bepaalt alleen wanneer er naar het auditlogboek wordt geschreven. U kunt er echter wel uit lezen via deze API.

Gebeurtenissen in het auditlogboek vervallen na twee jaar.

GET /api/v1/audit-logs

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

Deze API gebruikt paginering, geleverd door de parameters skip, before en after. AuditLogs worden geretourneerd in pagina's van 1000, geordend op when en id.

Het ophalen van elke 1000 logs kost 10 credits.

Standaard ontvangt u een lijst met de nieuwste items eerst. Op deze manier kunt u beginnen met pollen met skip=0, en pagineren totdat u het laatste record vindt dat u hebt geconsumeerd.

Als alternatief kunt u sorteren op oudste-eerst en pagineren totdat er geen records meer zijn.

Sorteren kan worden gedaan door order in te stellen op ASC of DESC. De standaard is ASC.

Zoeken op datum is mogelijk via before en after als tijdstempels met milliseconden. before en after zijn NIET inclusief.

AuditLog cURL Voorbeeld

Copy

curl --request GET \
  --url 'https://fastcomments.com/api/v1/audit-logs?tenantId=demo&API_KEY=DEMO_API_SECRET&skip=0&order=ASC&before=123&after=456'

AuditLog Verzoekstructuur

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    order?: 'ASC' | 'DESC'
    skip?: number
    before?: number
    after?: number
}

AuditLog Antwoordstructuur

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij een fout. **/
    reason?: string
    /** De logs! **/
    auditLogs: AuditLog[]
}

Reactiestructuur

Een Comment object stelt een opmerking voor die door een gebruiker is achtergelaten.

De relatie tussen ouder- en kindreacties wordt gedefinieerd via parentId.

De structuur van het Comment-object is als volgt:

Structuur van het Comment-object

Copy

interface Comment {
    /** READONLY: Zet op true als de spam-engine heeft vastgesteld dat het commentaar spam is. **/
    aiDeterminedSpam?: boolean
    /** Of het commentaar is goedgekeurd om te tonen. Zet op true bij het opslaan van het commentaar, anders wordt het verborgen. **/
    approved?: boolean
    /** De avatar van de gebruiker. **/
    avatarSrc?: string
    /** Kindreacties. Niet in alle scenario's gevuld. Gebruikt wanneer asTree via de API op true is gezet. **/
    children: Comment[]
    /** De onbewerkte opmerking van de schrijver. **/
    comment: string
    /** READONLY: De opmerking van de schrijver geparseerd naar HTML. **/
    commentHTML?: string
    /** Het e-mailadres van de schrijver. Vereist als anoniem reageren is uitgeschakeld. **/
    commenterEmail?: string
    /** De link van de schrijver (bijv. hun blog). **/
    commenterLink?: string
    /** De naam van de schrijver. Altijd vereist. Als niet beschikbaar, zet iets als "Anoniem". **/
    commenterName: string
    /** De datum waarop de opmerking is geplaatst, in UTC epoch. **/
    date: number
    /** Het "weergavelabel" voor het commentaar - bijvoorbeeld "Admin", "Moderator", of iets als "VIP User". **/
    displayLabel?: string
    /** Het domein waarop de opmerking is geplaatst. **/
    domain?: string
    /** READONLY: Het aantal keer dat het commentaar is gemarkeerd. **/
    flagCount?: number
    /** De #hashtags die in de opmerking zijn geschreven en succesvol zijn geparseerd. Je kunt ook hashtags handmatig toevoegen voor query's, maar deze worden niet automatisch in de opmerkingstekst weergegeven. **/
    hashTags?: CommentHashTag[]
    /** READONLY: Bevat de opmerking afbeeldingen? **/
    hasImages?: boolean
    /** READONLY: Bevat de opmerking links? **/
    hasLinks?: boolean
    /** READONLY: De unieke id van het commentaar. **/
    id: string
    /** Alleen bij aanmaak! Dit wordt gehasht voor opslag. **/
    ip?: string
    /** READONLY: Heeft de huidige gebruiker de auteur van dit commentaar geblokkeerd? **/
    isBlocked?: boolean
    /** READONLY: Is het commentaar door een admin geschreven? Automatisch ingesteld op basis van userId. **/
    isByAdmin?: boolean
    /** READONLY: Is het commentaar door een moderator geschreven? Automatisch ingesteld op basis van userId. **/
    isByModerator?: boolean
    /** Zet op true als het commentaar zacht verwijderd is (er moest een placeholder blijven vanwege een andere configuratie). **/
    isDeleted?: boolean
    /** Zet op true als het account van de gebruiker is verwijderd en het commentaar moest worden behouden. **/
    isDeletedUser?: boolean
    /** READONLY: Is het gemarkeerd door de momenteel ingelogde gebruiker (contextUserId)? **/
    isFlagged?: boolean
    /** Is het commentaar vastgezet? **/
    isPinned?: boolean
    /** Is het commentaar vergrendeld voor nieuwe reacties (moderators kunnen nog steeds reageren)? **/
    isLocked?: boolean
    /** Is het commentaar spam? **/
    isSpam?: boolean
    /** READONLY: Is het commentaar naar beneden gestemd voor de huidige gebruiker (contextUserId)? **/
    isVotedDown?: boolean
    /** READONLY: Is het commentaar omhoog gestemd voor de huidige gebruiker (contextUserId)? **/
    isVotedUp?: boolean
    /** De locale van het commentaar. Indien niet opgegeven, wordt deze afgeleid van de Accept-Language 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: De @mentions in het commentaar die succesvol zijn geparseerd. **/
    mentions?: CommentUserMention[]
    /** Optionele metadata geassocieerd met het commentaar. **/
    meta?: Record<string, string | number | boolean>
    /** De optionele lijst met moderation group ids die aan dit commentaar zijn gekoppeld. **/
    moderationGroupIds?: string[]|null
    /** READONLY: De id van het stemobject dat overeenkomt met de stem van de huidige gebruiker (contextUserId) op dit commentaar. **/
    myVoteId?: string
    /** Of er meldingen zijn verzonden voor dit commentaar naar reageerders. Om te voorkomen dat meldingen worden verzonden bij imports, zet dit op true. **/
    notificationSentForParent?: boolean
    /** Of er meldingen zijn verzonden voor dit commentaar naar tenant-gebruikers. Om te voorkomen dat meldingen worden verzonden bij imports, zet dit op true. **/
    notificationSentForParentTenant?: boolean
    /** De titel van de pagina waarop dit commentaar stond. **/
    pageTitle?: string
    /** Als we op een opmerking reageren, is dit de ID waarop we reageren. **/
    parentId?: string|null
    /** Of het commentaar als beoordeeld is gemarkeerd. **/
    reviewed: boolean
    /** De tenant-id waartoe het commentaar behoort. **/
    tenantId: string
    /** De gebruiker die het commentaar heeft geschreven. Automatisch aangemaakt bij het opslaan van een commentaar met een naam/e-mail. **/
    userId?: string|null
    /** De URL naar de locatie waarop dit commentaar zichtbaar is, zoals een blogpost. **/
    url: string
    /** Een "opgeschoonde" versie van de urlId die je aan ons doorgeeft. Bij opslaan geef je dit veld op, maar bij ophalen wordt dit "opgeschoond" en wordt je oorspronkelijke waarde verplaatst naar "urlIdRaw". **/
    urlId: string
    /** READONLY: De oorspronkelijke urlId die je ons hebt gegeven. **/
    urlIdRaw?: string
    /** Is de gebruiker en dit commentaar geverifieerd? **/
    verified: boolean
    /** Aantal stemmen omhoog. **/
    votesUp?: number
    /** Aantal stemmen omlaag. **/
    votesDown?: number
    /** De "karma" van het commentaar (= stemmen omhoog - stemmen omlaag). **/
    votes?: number
}

Sommige van deze velden zijn gemarkeerd als READONLY - deze worden door de API geretourneerd maar kunnen niet worden ingesteld.

Structuur van de opmerkingstekst

Opmerkingen worden geschreven in een FastComments-variant van markdown, wat gewoon markdown is plus traditionele bbcode-stijl tags voor afbeeldingen, zoals [img]path[/img].

Tekst wordt in twee velden opgeslagen. De tekst die de gebruiker invoerde wordt ongewijzigd opgeslagen in het veld comment. Dit wordt gerenderd en opgeslagen in het veld commentHTML.

De toegestane HTML-tags zijn b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, and br.

Het wordt aangeraden de HTML te renderen, aangezien het een zeer kleine subset van HTML is, het bouwen van een renderer is vrij eenvoudig. Er zijn bijvoorbeeld meerdere libraries voor React Native en Flutter die hierbij kunnen helpen.

Je kunt ervoor kiezen de niet-genormaliseerde waarde van het veld comment te renderen. Een voorbeeldparser vind je hier..

De voorbeeldparser kan ook aangepast worden om met HTML te werken en de HTML-tags om te zetten naar de verwachte elementen voor rendering op jouw platform.

Tagging

Wanneer gebruikers in een opmerking worden getagd, wordt de informatie opgeslagen in een lijst genaamd mentions. Elk object in die lijst heeft de volgende structuur.

Het Comment Vermeldingen-object

Copy

Run

interface CommentUserMention {
    /** De gebruikers-id. Voor SSO-gebruikers wordt hier je tenant-id als prefix toegevoegd. **/
    id: string
    /** De uiteindelijke @mention tekst, inclusief het @-symbool. **/
    tag: string
    /** De oorspronkelijke @mention tekst, inclusief het @-symbool. **/
    rawTag: string
    /** Welk type gebruiker is getagd. user = FastComments.com-account. sso = SSOUser. **/
    type: 'user'|'sso'
    /** Als de gebruiker zich afmeldt voor meldingen, wordt dit nog steeds op true gezet. **/
    sent: boolean
}

HashTags

Wanneer hashtags worden gebruikt en succesvol geparseerd, wordt de informatie opgeslagen in een lijst genaamd hashTags. Elk object in die lijst heeft de volgende structuur. Hashtags kunnen ook handmatig aan de hashTags-array van een opmerking worden toegevoegd voor query-doeleinden, als retain is ingesteld.

Het Comment HashTag-object

Copy

Run

interface CommentHashTag {
    /** De hashtag-id. **/
    id: string
    /** De uiteindelijke #hashtag tekst, inclusief het #-symbool. **/
    tag: string
    /** Als de hashtag is gekoppeld aan een aangepaste URL, wordt deze hier gedefinieerd. **/
    url?: string
    /** Of we de hashtag moeten behouden, ook als deze niet in de opmerkingstekst voorkomt, wanneer de opmerking wordt bijgewerkt. Handig om opmerkingen te taggen zonder de tekst te wijzigen. **/
    retain?: boolean
}

GET /api/v1/comments

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

Deze API wordt gebruikt om reacties op te halen voor weergave aan een gebruiker. Bijvoorbeeld filtert hij automatisch niet-goedgekeurde of spamreacties eruit.

Paginering

Paginering kan op een van twee manieren worden gedaan, afhankelijk van prestatie-eisen en gebruiksgeval:

Snelste: Precalculated Pagination:
1. Dit is hoe FastComments werkt wanneer u onze vooraf gebouwde widgets en clients gebruikt.
2. Het klikken op "next" verhoogt eenvoudigweg het paginanummer.
3. U kunt dit zien als opgehaald via een key-value store.
4. Definieer op deze manier eenvoudig een page-parameter beginnend bij 0 en een sorteerrichting als direction.
5. Paginagroottes kunnen worden aangepast via aanpassingsregels.
Meest flexibel: Flexible Pagination:
1. Op deze manier kunt u aangepaste limit- en skip-parameters definiëren. Geef geen page door.
2. Sorteerrichting direction wordt ook ondersteund.
3. limit is het totale aantal dat wordt geretourneerd nadat skip is toegepast.
  - Voorbeeld: stel skip = 200, limit = 100 wanneer page size = 100 en page = 2.
4. Kindreacties tellen nog steeds mee in de paginering. U kunt dit omzeilen met de optie asTree.
  - U kunt kinderen pagineren via limitChildren en skipChildren.
  - U kunt de diepte van de teruggegeven threads beperken via maxTreeDepth.

Threads

Wanneer u Precalculated Pagination gebruikt, worden reacties gegroepeerd per pagina en beïnvloeden reacties in threads de gehele pagina.
1. Op deze manier kunnen threads op de client worden bepaald op basis van parentId.
2. Bijvoorbeeld, bij een pagina met één topniveau-reactie en 29 antwoorden, en het instellen van page=0 in de API - krijgt u alleen de topniveau-reactie en de 29 kinderen.
3. Voorbeeldafbeelding die meerdere pagina's illustreert.
Wanneer u Flexible Pagination gebruikt, kunt u een parentId-parameter definiëren.
1. Stel deze in op null om alleen topniveau-reacties te krijgen.
2. Om vervolgens threads te bekijken, roept u de API opnieuw aan en geeft u parentId door.
3. Een gebruikelijke oplossing is om een API-aanroep te doen voor de topniveau-reacties en vervolgens parallelle API-aanroepen te doen om reacties op te halen voor de kinderen van elke reactie.
NIEUW sinds feb 2023! Ophalen als een boom met &asTree=true.
1. U kunt dit zien als Flexible Pagination as a Tree.
2. Alleen de topniveau-reacties tellen mee in de paginering.
3. Stel parentId=null in om de boom bij de root te starten (u moet parentId instellen).
4. Stel skip en limit in voor paginering.
5. Stel asTree in op true.
6. De credits-kosten nemen toe met 2x, omdat onze backend in dit scenario veel meer werk moet doen.
7. Stel maxTreeDepth, limitChildren en skipChildren in naar wens.

Bomen uitgelegd

Wanneer u asTree gebruikt, kan het moeilijk zijn om over paginering na te denken. Hier is een handige afbeelding:

Diagram van boom-paginering

Reacties ophalen in de context van een gebruiker

De /comments API kan in twee contexten worden gebruikt, voor verschillende gebruiksgevallen:

Voor het retourneren van reacties gesorteerd en gelabeld met informatie voor het bouwen van uw eigen client.
- Gebruik in dit geval een queryparameter contextUserId.
Voor het ophalen van reacties vanaf uw backend voor aangepaste integraties.
- Het platform zal standaard naar dit terugvallen zonder contextUserId.

Reacties Voorafberekende 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'

Reacties Flexibele 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'

Reacties Flexibele Paginering in Gebruikerscontext

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'

Reacties Flexibele Paginering in Gebruikerscontext voor Alleen Topniveau Reacties

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'

Reacties als boom ophalen

Het is mogelijk om reacties terug te krijgen als een boom, waarbij alleen de topniveau-reacties meetellen voor de paginering.

Reacties Als Boom in Gebruikerscontext

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'

Wilt u alleen de topniveau-reacties en de directe kinderen ophalen? Hier is één manier:

Reacties Als Boom met Maximale Diepte

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'

Echter, in uw UI moet u misschien weten of u op elke reactie een knop "toon reacties" moet weergeven. Bij het ophalen van reacties via een boom is er een hasChildren-eigenschap toegevoegd aan reacties wanneer van toepassing.

Reacties als boom ophalen, zoeken op hashtag

Het is mogelijk om op hashtag te zoeken met de API, over uw gehele tenant (niet beperkt tot één pagina of urlId).

In dit voorbeeld laten we urlId weg en zoeken we op meerdere hashtags. De API retourneert alleen reacties die alle gevraagde hashtags bevatten.

Reacties Als Boom in Gebruikerscontext, Op 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 verzoekparameters

Structuur van Reactiesaanvraag

Copy

interface CommentsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** De urlId (pagina-url, of artikel-id) waarmee de reacties zijn geassocieerd. **/
    urlId?: string
    /** Beperk de geretourneerde reacties tot die van deze gebruiker. **/
    userId?: string
    /** Gebruik dit om te zoeken op hashtag. Om naar de doorsnede van meerdere hashtags te filteren, gebruik &hashTag=a&hashTag=b. **/
    hashTag?: string
    /** De sorteerrichting. Standaard is MR (Meest Relevant). Andere opties zijn OF (Oudste Eerst) en NF (Nieuwste Eerst). **/
    direction?: 'MR' | 'OF' | 'NF'
    /** Precalculated Pagination: de pagina om op te halen, beginnend met 0. Geef -1 door om alle reacties op te halen (tot 250). **/
    page?: number
    /** Flexibele paginering: hoeveel reacties moeten we retourneren? **/
    limit?: number
    /** Flexibele paginering: hoeveel kindreacties moeten we voor elk ouder-item retourneren? **/
    limitChildren?: number
    /** Flexibele paginering: hoeveel reacties moeten we overslaan? **/
    skip?: number
    /** Flexibele paginering: hoeveel kindreacties moeten we overslaan voor elk ouder-item? **/
    skipChildren?: number
    /** Voor het bepalen van geblokkeerde en gemarkeerde reacties. **/
    contextUserId?: string
    /** Voor het bepalen van geblokkeerde en gemarkeerde reacties. **/
    anonUserId?: string
    /** Voor het ophalen van kindreacties. **/
    parentId?: string
    /** Voor het ophalen als een boom. **/
    asTree?: boolean
    /** Hoe ver in de boom moeten we gegevens teruggeven? 0 geeft geen kinderen terug. 1 geeft onmiddellijke kinderen terug, enz. **/
    maxTreeDepth?: number
}

De respons

Structuur van Reactiesrespons

Copy

interface CommentsResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De reacties! **/
    comments: Comment[]
}

Handige tips

URL ID

Waarschijnlijk wilt u de Comment-API gebruiken met de parameter urlId. U kunt eerst de Pages-API aanroepen om te zien hoe de voor u beschikbare urlId-waarden eruitzien.

Anonieme acties

Voor anoniem reageren wilt u waarschijnlijk anonUserId doorgeven bij het ophalen van reacties, en bij het uitvoeren van markeringen en blokkeringen.

(!) Dit is vereist voor veel app stores omdat gebruikers in staat moeten zijn user-generated content die ze zien te markeren, zelfs als ze niet zijn ingelogd. Het niet doen hiervan kan ertoe leiden dat uw app uit genoemde store wordt verwijderd.

Reacties worden niet geretourneerd

Controleer of uw reacties zijn goedgekeurd en geen spam zijn.

GET /api/v1/comments/:id

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

Deze API biedt de mogelijkheid om een enkele reactie op te halen op basis van id.

Reacties Ophalen per ID cURL Voorbeeld

Copy

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

Reactie Ophalen per ID Verzoekstructuur

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Reacties Ophalen per ID Antwoordstructuur

Copy

interface CommentGetByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found' | 'missing-id'
    /** Opgenomen bij een fout. **/
    reason?: string
    /** De reactie! **/
    comment?: Comment
}

POST /api/v1/comments

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

Dit API-eindpunt biedt de mogelijkheid om reacties te maken.

Veelvoorkomende gebruikssituaties zijn aangepaste UIs, integraties of imports.

Opmerkingen:

Deze API kan het reactiewidget "live" bijwerken indien gewenst (dit verhoogt de creditsCost van 1 naar 2).
Deze API maakt automatisch gebruikersobjecten in ons systeem aan als een e-mailadres wordt opgegeven.
Poging om twee reacties op te slaan met verschillende e-mails, maar dezelfde gebruikersnaam, resulteert in een fout voor de tweede reactie.
Als u parentId opgeeft, en een kindreactie heeft notificationSentForParent als false, zullen wij meldingen voor de ouderreactie verzenden. Dit gebeurt elk uur (we groeperen de meldingen om het aantal verzonden e-mails te verminderen).
Als u welkomst-e-mails wilt verzenden bij het aanmaken van gebruikers, of e-mails voor reactie-verificatie, zet sendEmails op true in de queryparameters.
Reacties die via deze API worden gemaakt verschijnen in de Analytics- en Moderation-pagina's van de beheerapp.
"ongepaste woorden" blijven nog steeds gemaskeerd in de namen van reageerders en de reactietekst als de instelling is ingeschakeld.
Reacties gemaakt via deze API kunnen desgewenst nog steeds op spam worden gecontroleerd.
Configuraties zoals maximale reactielengte, indien geconfigureerd via de Customization Rule-beheerpagina, zijn hier van toepassing.

De minimale gegevens die vereist zijn om te verzenden en die in het reactiewidget worden weergegeven, zijn als volgt:

Minimaal Comment POST cURL Voorbeeld

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
}'

Een realistischer verzoek kan er als volgt uitzien:

Comment POST cURL Voorbeeld

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"
}'

Structuur van Comment POST-verzoek

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** Of de reactie "live" moet verschijnen voor gebruikers die instanties van het reactiewidget met dezelfde urlId bekijken. OPMERKING: Verdubbelt de credits-kosten van 1 naar 2. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

Structuur van Comment POST-respons

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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';
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De aangemaakte reactie. **/
    comment?: Comment
    /** De bijbehorende gebruiker, die mogelijk al bestond of niet. **/
    user?: User
}

PATCH /api/v1/comments/:id

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

Dit API-eindpunt biedt de mogelijkheid om één reactie bij te werken.

Opmerkingen:

Deze API kan de reactie-widget "live" bijwerken indien gewenst (dit verhoogt de basis creditsCost van 1 naar 2).
- Dit kan het migreren van reacties tussen pagina's "live" maken (door urlId te wijzigen).
- Migraties kosten aanvullend 2 credits omdat pagina's vooraf worden berekend en dit CPU-intensief is.
In tegenstelling tot de create API zal deze API GEEN gebruikersobjecten automatisch aanmaken in ons systeem als er een e‑mail wordt opgegeven.
Reacties die via deze API worden bijgewerkt, kunnen indien gewenst nog steeds op spam worden gecontroleerd.
Configuratie zoals maximale reactielengte, indien geconfigureerd via de Customization Rule admin page, is hier van toepassing.
Om gebruikers toe te staan hun reactietekst bij te werken, kunt u eenvoudig comment in de request body opgeven. Wij genereren dan de resulterende commentHTML.
- Als u zowel comment als commentHTML definieert, zullen wij de HTML niet automatisch genereren.
- Als de gebruiker mentions of hashtags toevoegt in de nieuwe tekst, wordt dit nog steeds verwerkt zoals bij de POST API.
Wanneer u commenterEmail op een reactie bijwerkt, is het het beste ook userId op te geven. Anders moet u ervoor zorgen dat de gebruiker met dit e‑mailadres tot uw tenant behoort, anders mislukt het verzoek.

Minimaal PATCH cURL-voorbeeld voor reactie

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"
}'

Structuur van PATCH-verzoek voor reactie

Copy

interface CommentPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** De gebruiker die de update uitvoert. Kan indien gewenst worden gebruikt om te controleren of zij de reactie kunnen bewerken.  **/
    contextUserId?: string
    /** Moeten we controleren of de nieuwe reactie op spam lijkt?  **/
    doSpamCheck?: 'true' | 'false'
    /** Of de reactie "live" moet verschijnen voor gebruikers die instanties van de reactie-widget met dezelfde urlId bekijken. OPMERKING: verdubbelt de creditkosten van 1 naar 2. **/
    isLive?: 'true' | 'false'
}

Structuur van PATCH-respons voor reactie

Copy

interface CommentPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/comments/:id

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

Deze API-endpoint biedt de mogelijkheid om een reactie te verwijderen.

Opmerkingen:

Deze API kan, indien gewenst, de comment-widget "live" bijwerken (dit verhoogt creditsCost van 1 naar 2).
Deze API verwijdert alle onderliggende reacties.

Comment DELETE cURL-voorbeeld

Copy

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

Structuur van Comment DELETE-verzoek

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** De gebruiker die de update uitvoert. Kan, indien gewenst, worden gebruikt om te controleren of de gebruiker de reactie mag verwijderen.  **/
    contextUserId?: string
    /** Of de reactie "live" moet worden verwijderd voor gebruikers die instanties van de comment-widget met dezelfde urlId bekijken. OPMERKING: verdubbelt de credits-kosten van 1 naar 2. **/
    isLive?: 'true' | 'false'
}

Structuur van Comment DELETE-respons

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'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

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

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

Deze API-endpoint biedt de mogelijkheid om een opmerking voor een specifieke gebruiker te markeren.

Opmerkingen:

Deze oproep moet altijd worden gedaan in de context van een gebruiker. De gebruiker kan een FastComments.com-gebruiker, SSO-gebruiker of Tenant-gebruiker zijn.
Als er een drempel is ingesteld waarbij een opmerking bij voldoende flags wordt verborgen, wordt de opmerking meteen automatisch verborgen nadat het gedefinieerde aantal flags is bereikt.
Nadat de opmerking automatisch is afgekeurd (verborgen), kan deze alleen opnieuw worden goedgekeurd door een beheerder of moderator. Het verwijderen van de vlag zal de opmerking niet opnieuw goedkeuren.

Voorbeeld cURL-aanvraag voor het markeren van een opmerking

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'

Voor anoniem flaggen moeten we een anonUserId opgeven. Dit kan een ID zijn die de anonieme sessie vertegenwoordigt, of een willekeurige UUID. Dit stelt ons in staat om het markeren en demarkeren van opmerkingen te ondersteunen, zelfs als een gebruiker niet is ingelogd. Op deze manier kan de opmerking als gemarkeerd worden weergegeven wanneer opmerkingen worden opgehaald met dezelfde anonUserId.

Voorbeeld cURL-aanvraag voor het anoniem markeren van een opmerking

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'

Structuur van het verzoek voor commentaarmarkering

Copy

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

Structuur van de response voor commentaarmarkering

Copy

interface CommentFlagResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'not-found' | 'missing-user-id' | 'missing-anon-user-id'
    /** Opgenomen bij fout. **/
    reason?: string
    /** Werd de opmerking afgekeurd (verborgen) omdat deze te vaak is gemarkeerd? **/
    wasUnapproved?: boolean;
}

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

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

Dit API-eindpunt maakt het mogelijk om de vlag van een reactie voor een specifieke gebruiker te verwijderen.

Opmerkingen:

Deze oproep moet altijd worden gedaan in de context van een gebruiker. De gebruiker kan een FastComments.com User, SSO User, or Tenant User zijn.
Nadat een reactie automatisch is afgekeurd (verborgen) - kan de reactie alleen opnieuw worden goedgekeurd door een beheerder of moderator. Het verwijderen van de vlag zal de reactie niet opnieuw goedkeuren.

Voorbeeld cURL-aanvraag: vlag van reactie verwijderen

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'

Voor anoniem vlaggen moeten we een anonUserId opgeven. Dit kan een ID zijn die de anonieme sessie vertegenwoordigt, of een willekeurige UUID.

Voorbeeld cURL-aanvraag: anonieme reactie vlag verwijderen

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'

Structuur van het verzoek: vlag van reactie verwijderen

Copy

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

Structuur van de respons: vlag van reactie verwijderen

Copy

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

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

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

Dit API-eindpunt biedt de mogelijkheid om een gebruiker te blokkeren die een bepaalde opmerking heeft geschreven. Het ondersteunt blokkeren van opmerkingen geschreven door FastComments.com-gebruikers, SSO-gebruikers en tenantgebruikers.

Het ondersteunt een body-parameter commentIdsToCheck om te controleren of andere mogelijk zichtbare opmerkingen op de client geblokkeerd of gedeblokkeerd moeten worden nadat deze actie is uitgevoerd.

Notities:

Deze oproep moet altijd worden uitgevoerd in de context van een gebruiker. De gebruiker kan een FastComments.com-gebruiker, een SSO-gebruiker of een tenantgebruiker zijn.
Het userId in het verzoek is de gebruiker die de blokkering uitvoert. Bijvoorbeeld: User A wil User B blokkeren. Geef userId=User A en de comment-id die User B schreef.
Volledig anonieme opmerkingen (geen user id, geen e-mail) kunnen niet worden geblokkeerd en er wordt een fout geretourneerd.

cURL-voorbeeld: Opmerking blokkeren

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'

Voor anonieme blokkering moeten we een anonUserId opgeven. Dit kan een ID zijn die de anonieme sessie vertegenwoordigt, of een willekeurige UUID. Dit stelt ons in staat om opmerkingen te blokkeren, zelfs als een gebruiker niet is ingelogd, door de opmerkingen op te halen met hetzelfde anonUserId.

cURL-voorbeeld: Anonieme opmerking blokkeren

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'

Aanvraagstructuur: Opmerking blokkeren

Copy

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

Reactiestructuur: Opmerking blokkeren

Copy

interface CommentBlockResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** Als commentIdsToCheck gedefinieerd is, vermeldingen in deze map met de waarde true zijn ook geblokkeerd. **/
    commentStatuses?: Record<string, boolean>;
}

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

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

Deze API-endpoint biedt de mogelijkheid om een gebruiker die een bepaalde reactie schreef te deblokkeren. Het ondersteunt het deblokkeren van reacties geschreven door FastComments.com Users, SSO Users, and Tenant Users.

Het ondersteunt een body-parameter commentIdsToCheck om te controleren of andere mogelijk zichtbare reacties in de client na deze actie geblokkeerd of gedeblokkeerd moeten worden.

Notes:

Deze oproep moet altijd worden gedaan in de context van een gebruiker. De gebruiker kan een FastComments.com User, SSO User, or Tenant User zijn.
The userId in the request is the user that is die het deblokkeren uitvoert. For example: User A wil User B deblokkeren. Pass userId=User A and the comment id that User B wrote.
Completely anonymous comments (no user id, no email) cannot be blocked and an error will be returned.

cURL-voorbeeld: het deblokkeren van een reactie

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'

cURL-voorbeeld: het deblokkeren van een anonieme reactie

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'

Structuur van de aanvraag voor het deblokkeren van een reactie

Copy

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

Structuur van de response voor het deblokkeren van een reactie

Copy

interface CommentUnBlockResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** Als commentIdsToCheck is gedefinieerd, zijn items in deze map met true nog steeds geblokkeerd. Als false, wilt u mogelijk de reacties voor de gebruiker weer zichtbaar maken zodat ze niet hoeven te verversen. **/
    commentStatuses?: Record<string, boolean>;
}

E-mailsjabloonstructuur

Een EmailTemplate-object vertegenwoordigt de configuratie voor een aangepast e-mailsjabloon voor een tenant.

Het systeem selecteert het e-mailsjabloon dat gebruikt wordt via:

Het type-identifier, dit noemen we emailTemplateId. Dit zijn constanten.
De domain. We proberen eerst een sjabloon te vinden voor de domain waaraan het gerelateerde object (zoals een Comment) is gekoppeld, en als er geen overeenkomst wordt gevonden zullen we proberen een sjabloon te vinden waarbij domain null of * is.

De structuur van het EmailTemplate-object is als volgt:

Structuur van het EmailTemplate

Copy

interface EmailTemplate {
    id: string
    tenantId: string
    emailTemplateId: string
    displayName: string
    /** ALLEEN LEZEN **/
    createdAt: string
    /** ALLEEN LEZEN **/
    updatedAt: string
    /** ALLEEN LEZEN **/
    updatedByUserId: string
    /** De domain waaraan het sjabloon gekoppeld moet worden. **/
    domain?: string | '*' | null
    /** De inhoud van het e-mailsjabloon in EJS-syntaxis. **/
    ejs: string
    /** Een map van overschreven vertaalingssleutels naar waarden, voor elke ondersteunde locale. **/
    translationOverridesByLocale: Record<string, Record<string, string>>
    /** Een object dat de rendercontext van het sjabloon vertegenwoordigt. **/
    testData: object
}

Opmerkingen

Je kunt de geldige emailTemplateId-waarden verkrijgen via het /definitions-endpoint.
Het /definitions-endpoint bevat ook de standaardvertalingen en testgegevens.
Sjablonen slaan niet op als de structuur of testgegevens ongeldig zijn.

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

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

Individuele EmailTemplates kunnen worden opgehaald met hun bijbehorende id (NIET emailTemplateId).

EmailTemplate per ID cURL Voorbeeld

Copy

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

EmailTemplate per ID Aanvraagstructuur

Copy

interface EmailTemplatesByIdRequestQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate per ID Responsstructuur

Copy

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

GET /api/v1/email-templates

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

Deze API gebruikt paginering, geleverd door de queryparameter page. EmailTemplates worden geretourneerd in pagina's van 100, gesorteerd op createdAt en vervolgens id.

EmailTemplate cURL-voorbeeld

Copy

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

EmailTemplate Aanvraagstructuur

Copy

interface EmailTemplatesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** De pagina om op te halen, beginnend bij 0. **/
    page: number
}

EmailTemplate Antwoordstructuur

Copy

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

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

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

Dit API-eindpunt biedt de mogelijkheid om een e-mailtemplate bij te werken door alleen de id en de attributen die bijgewerkt moeten worden op te geven.

Houd er rekening mee dat alle validaties die gelden bij het aanmaken van een template ook van toepassing zijn, bijvoorbeeld:

De template moet renderen. Dit wordt bij elke update gecontroleerd.
Er mogen geen dubbele templates voor hetzelfde domein bestaan (anders wordt er één stilzwijgend genegeerd).

EmailTemplate PATCH cURL Voorbeeld

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 Verzoekstructuur

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate PATCH Responsstructuur

Copy

interface EmailTemplatePatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    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';  
    /** Opgenomen bij een fout. **/
    reason?: string
    /** Het bijgewerkte e-mailtemplate. **/
    emailTemplate?: EmailTemplate
}

POST /api/v1/email-templates

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

Dit API-endpoint biedt de mogelijkheid om e-mailsjablonen te maken.

Opmerkingen:

Je kunt niet meerdere sjablonen hebben met dezelfde emailTemplateId voor hetzelfde domein.
Maar je kunt wel een wildcard-sjabloon hebben (domain = *) en een domeinspecifiek sjabloon voor dezelfde emailTemplateId.
Het opgeven van domain is alleen relevant als je meerdere domeinen hebt, of specifieke sjablonen wilt gebruiken voor testen (domain ingesteld op localhost etc).
Als je domain opgeeft, moet dit overeenkomen met een DomainConfig. Bij een fout wordt een lijst met geldige domeinen verstrekt.
De sjabloonsyntaxis is EJS en wordt gerenderd met een timeout van 500ms. P99 voor renderen is <5ms, dus als je de 500ms bereikt is er iets mis.
Je sjabloon moet renderen met de opgegeven testData om op te slaan. Renderfouten worden samengevoegd en gerapporteerd op het dashboard (binnenkort via de API beschikbaar).

De minimale gegevens die nodig zijn om een sjabloon toe te voegen, zijn als volgt:

Minimaal EmailTemplate POST cURL Voorbeeld

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 %>."
}'

Je wilt mogelijk per site sjablonen hebben, in dat geval definieer je domain:

EmailTemplate POST cURL Voorbeeld

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 Verzoekstructuur

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST Antwoordstructuur

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

Dit API-eindpunt maakt het mogelijk e-mailsjablonen te bekijken.

Minimaal EmailTemplate Preview POST cURL-voorbeeld

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-aanvraagstructuur

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

EmailTemplate POST-antwoordstructuur

Copy

interface EmailTemplatePostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'unauthorized' | 'unexpected-param' | 'does-not-render';
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De gerenderde HTML bij succes. **/
    html?: string
}

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

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

Deze route verwijdert een enkele EmailTemplate op basis van id.

cURL-voorbeeld voor het verwijderen van EmailTemplate

Copy

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

Verzoeksstructuur voor het verwijderen van EmailTemplate

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Antwoordstructuur voor het verwijderen van EmailTemplate

Copy

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

Hashtagstructuur

Een HashTag object vertegenwoordigt een tag die door een gebruiker kan worden achtergelaten. HashTags kunnen worden gebruikt om naar een extern stuk inhoud te linken of om gerelateerde opmerkingen met elkaar te verbinden.

De structuur van het HashTag object is als volgt:

HashTag-structuur

Copy

interface HashTag {
    /** Moet beginnen met de "#" of het gewenste teken. **/
    tag: string
    /** Een optionele URL waar de hashtag naartoe kan verwijzen. In plaats van opmerkingen te filteren op hashtag, zal de UI hiernaartoe doorverwijzen bij een klik. **/
    url?: string
    /** ALLEEN-LEZEN **/
    createdAt: string
}

Opmerkingen:

In sommige API endpoints zie je dat de hashtag in de URL wordt gebruikt. Vergeet niet waarden te URI-encoderen. Bijvoorbeeld, # moet in plaats daarvan worden weergegeven als %23.
Sommige van deze velden zijn gemarkeerd als READONLY - deze worden door de API geretourneerd maar kunnen niet worden ingesteld.

GET /api/v1/hash-tags

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

Deze API gebruikt paginering, geleverd door de queryparameter page. HashTags worden geretourneerd in pagina's van 100, gesorteerd op tag.

HashTag cURL Voorbeeld

Copy

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

HashTag Verzoekstructuur

Copy

interface HashTagsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** De op te halen pagina, beginnend bij 0. **/
    page: number
}

HashTag Responsstructuur

Copy

interface HashTagsResponse {
    status: 'success' | 'failed'
    /** Wordt opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Wordt opgenomen bij mislukking. **/
    reason?: string
    /** De hashtags! **/
    hashTags: HashTag[]
}

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

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

Deze route biedt de mogelijkheid om een enkele HashTag bij te werken.

HashTag Bijwerken cURL-voorbeeld

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`"
}'

Structuur van HashTag-bijwerkverzoek

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het antwoord bij het bijwerken van een HashTag

Copy

interface HashTagPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    hashTag?: HashTag; // Bij succes geven we de volledig bijgewerkte hashtag terug.
}

POST /api/v1/hash-tags

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

Deze route biedt de mogelijkheid om een enkele HashTag toe te voegen.

HashTag Aanmaken cURL Voorbeeld

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 Aanmaak Request Structuur

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Aanmaak Response Structuur

Copy

interface HashTagPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    hashTag?: HashTag; // We geven de volledig aangemaakte hashtag terug bij succes.
}

POST /api/v1/hash-tags/bulk

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

Deze route biedt de mogelijkheid om tot 100 HashTag-objecten tegelijk toe te voegen.

HashTag Bulk Create cURL-voorbeeld

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 Create Request-structuur

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

HashTag Bulk Create Response-structuur

Copy

interface HashTagBulkPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    results?: HashTagPostResponse[]; // We geven een lijst met HashTagPostResponse-objecten terug voor elke opgegeven tag.
}

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

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

Deze route verwijdert een HashTag op basis van de opgegeven tag.

Houd er rekening mee dat, tenzij automatische creatie van HashTag is uitgeschakeld, hashtags opnieuw kunnen worden aangemaakt wanneer een gebruiker de hashtag opgeeft bij het plaatsen van een reactie.

Voorbeeld cURL-verzoek voor HashTag-verwijdering

Copy

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

Structuur van het verzoek voor HashTag-verwijdering

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het antwoord op HashTag-verwijdering

Copy

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

Moderatorstructuur

Een Moderator-object vertegenwoordigt de configuratie voor een moderator.

Er zijn drie typen moderators:

Beheerdersgebruikers die de isCommentModeratorAdmin flag hebben.
SSO-gebruikers met de isCommentModeratorAdmin flag.
Gewone commentatoren, of FastComments.com-gebruikers, die worden uitgenodigd als Moderators.

De Moderator-structuur wordt gebruikt om de moderatiestatus van use case 3 weer te geven.

Als u een gebruiker via de API wilt uitnodigen om moderator te worden, gebruik dan de Moderator API door een Moderator aan te maken en ze te inviting.

Als de gebruiker geen FastComments.com-account heeft, helpt de uitnodigings-e-mail hen bij het opzetten. Als ze al een account hebben, krijgen ze moderatietoegang tot uw tenant en zal het userId van het Moderator-object worden bijgewerkt om naar hun gebruiker te verwijzen. U zult geen API-toegang tot hun gebruiker hebben, omdat deze in dat geval van henzelf is en wordt beheerd door FastComments.com.

Als u volledige beheer over het account van de gebruiker nodig heeft, raden we aan ofwel SSO te gebruiken, of ze toe te voegen als een Tenant-gebruiker en vervolgens een Moderator-object toe te voegen om hun statistieken bij te houden.

De Moderator-structuur kan worden gebruikt als een mechanisme voor statistiekregistratie voor use cases 1 en 2. Nadat u de gebruiker hebt aangemaakt, voegt u een Moderator-object toe met hun userId gedefinieerd en hun statistieken worden bijgehouden op de Pagina voor comment-moderatoren.

De structuur van het Moderator-object is als volgt:

Structuur van Moderator

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

Deze route retourneert een enkele moderator op basis van het id.

cURL-voorbeeld: Moderator op ID

Copy

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

Verzoekstructuur voor Moderator

Copy

interface ModeratorByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Responsstructuur voor Moderator

Copy

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

GET /api/v1/moderators

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

Deze API gebruikt paginering via de queryparameter skip. Moderators worden geretourneerd in pagina's van 100, gesorteerd op createdAt en id.

De kosten zijn gebaseerd op het aantal geretourneerde moderators; het kost 1 credit per 10 geretourneerde moderators.

Moderator cURL-voorbeeld

Copy

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

Moderator Verzoekstructuur

Copy

interface ModeratorsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Het aantal moderators om over te slaan voor paginering. **/
    skip?: number
}

Moderator Responsstructuur

Copy

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

PATCH /api/v1/moderators/:id

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

Dit API-eindpunt biedt de mogelijkheid om een Moderator bij te werken via id.

Het bijwerken van een Moderator kent de volgende beperkingen:

De volgende waarden mogen niet worden opgegeven bij het bijwerken van een Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Als een userId is opgegeven, moet die gebruiker bestaan.
Als een userId is opgegeven, moet deze behoren tot dezelfde tenantId die in de queryparameters is opgegeven.
Twee moderators in dezelfde tenant kunnen niet worden toegevoegd met hetzelfde email.
U mag de tenantId die aan een Moderator is gekoppeld niet wijzigen.

Moderator PATCH cURL Voorbeeld

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 Verzoekstructuur

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator PATCH Antwoordstructuur

Copy

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

POST /api/v1/moderators

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

Deze route biedt de mogelijkheid om één Moderator toe te voegen.

Het aanmaken van een Moderator heeft de volgende beperkingen:

Een name en email moeten altijd worden opgegeven. Een userId is optioneel.
De volgende waarden mogen niet worden opgegeven bij het aanmaken van een Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Wanneer een userId is opgegeven, moet die gebruiker bestaan.
Wanneer een userId is opgegeven, moet die tot dezelfde tenantId behoren die in de queryparameters is opgegeven.
Twee moderators binnen dezelfde tenant kunnen niet worden toegevoegd met hetzelfde email.

We kunnen een Moderator aanmaken voor een gebruiker waarvan we alleen het e-mailadres kennen:

Moderator aanmaken via e-mail cURL voorbeeld

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"
}'

Of we kunnen een Moderator aanmaken voor een gebruiker die tot onze tenant behoort, om hun moderatiestatistieken bij te houden:

Moderator aanmaken via tenant-gebruiker cURL voorbeeld

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 aanmaken - Requeststructuur

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

Moderator aanmaken - Responsstructuur

Copy

interface ModeratorPostResponse {
    status: 'success' | 'failed'
    /** Inbegrepen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'name-required' | 'email-required' | 'unexpected-param' | 'not-found'
    /** Inbegrepen bij mislukking. **/
    reason?: string
    moderator?: Moderator; // We geven de volledig aangemaakte moderator terug bij succes.
}

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

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

Deze route biedt de mogelijkheid om één Moderator uit te nodigen.

De volgende beperkingen gelden om een uitnodigingsmail naar een Moderator te sturen:

De Moderator moet al bestaan.
De fromName mag niet langer zijn dan 100 characters.

Opmerkingen:

Als een gebruiker met het opgegeven e-mailadres al bestaat, wordt hij uitgenodigd om de opmerkingen van uw tenant te modereren.
Als een gebruiker met het opgegeven e-mailadres niet bestaat, leidt de uitnodigingslink die persoon door het aanmaken van een account.
De uitnodiging verloopt na 30 days.

We kunnen een Moderator aanmaken voor een gebruiker waarvan we alleen het e-mailadres kennen:

Voorbeeld cURL-verzoek voor moderatoruitnodiging

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'

Dit zal een e-mail sturen zoals Bob at TenantName is inviting you to be a moderator...

Structuur van het verzoek voor moderatoruitnodiging

Copy

interface ModeratorSendInviteQueryParams {
    tenantId: string
    API_KEY: string
    /** De e-mail die naar de gebruiker wordt gestuurd zal afkomstig lijken van deze naam. **/
    fromName: string
}

Structuur van de respons voor moderatoruitnodiging

Copy

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

DELETE /api/v1/moderators/:id

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

Deze route biedt het verwijderen van een Moderator op basis van het id.

cURL-voorbeeld: Moderator verwijderen

Copy

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

Structuur van het verwijderverzoek voor Moderator

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van de respons voor Moderator-verwijdering

Copy

interface ModeratorDeleteResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'not-found'
    /** Opgenomen bij een fout. **/
    reason?: string
}

Structuur aantal meldingen

Een NotificationCount object vertegenwoordigt het aantal ongelezen meldingen en metadata voor een gebruiker.

Als er geen ongelezen meldingen zijn, bestaat er geen NotificationCount voor de gebruiker.

NotificationCount-objecten worden automatisch aangemaakt en kunnen niet via de API worden gemaakt. Ze verlopen ook na één jaar.

U kunt het aantal ongelezen meldingen van een gebruiker wissen door hun NotificationCount te verwijderen.

De structuur van het NotificationCount-object is als volgt:

NotificationCount-structuur

Copy

interface NotificationCount {
    id: string // gebruikers-id
    count: number
    createdAt: string // datumstring
    expireAt: string // datumstring
}

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

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

Deze route retourneert een enkele NotificationCount op basis van user id. Bij SSO staat de user id in het formaat <tenant id>:<user id>.

Als er geen ongelezen meldingen zijn, zal er geen NotificationCount zijn - u krijgt dan een 404.

Dit verschilt van notifications/count doordat het veel sneller is, maar geen filtering toestaat.

NotificationCount per ID cURL-voorbeeld

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"}}

Structuur van NotificationCount-verzoek

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van NotificationCount-respons

Copy

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

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

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

Deze route verwijdert een enkele NotificationCount op basis van gebruikers-id. Bij SSO heeft de gebruikers-id het formaat <tenant id>:<user id>.

Dit wist de ongelezen meldingtelling van de gebruiker (het rode bel-icoon in de reactie-widget vervaagt en het aantal verdwijnt).

Voorbeeld cURL-verzoek voor DELETE NotificationCount

Copy

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

Structuur van verwijderingsverzoek voor NotificationCount

Copy

interface NotificationCountDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van antwoord op verwijdering van NotificationCount

Copy

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

Notificatiestructuur

Een Notification object vertegenwoordigt een notificatie voor een gebruiker.

Notification objects worden automatisch aangemaakt en kunnen niet via de API worden aangemaakt. Ze verlopen ook na één jaar. Notificaties kunnen niet worden verwijderd. Ze kunnen echter wel worden bijgewerkt om viewed op false te zetten, en je kunt zoeken op viewed.

Een gebruiker kan zich ook afmelden voor notificaties voor een specifiek comment door optedOut in de notificatie op true te zetten. Je kunt je weer aanmelden door het op false te zetten.

Er zijn verschillende notificatie-types - controleer relatedObjectType en type.

De manieren waarop notificaties worden aangemaakt zijn vrij flexibel en kunnen door veel scenario's worden getriggerd (zie NotificationType).

Op dit moment impliceert het bestaan van een Notification niet noodzakelijk dat er een e-mail is of zou moeten worden verzonden. In plaats daarvan worden de notificaties gebruikt voor de notificatiefeed en gerelateerde integraties.

De structuur voor het Notification object is als volgt:

Notification-structuur

Copy

enum NotificationObjectType {
    Comment = 0,
    Profile = 1,
    Tenant = 2
}
enum NotificationType {
    /** Als iemand op jou heeft geantwoord. **/
    RepliedToMe = 0,
    /** Als iemand ergens in een thread heeft geantwoord (zelfs kinderen van kinderen) van een thread waarop je hebt gereageerd. **/
    RepliedTransientChild = 1,
    /** Als je comment werd omhoog gestemd. **/
    VotedMyComment = 2,
    /** Als er een nieuw comment wordt achtergelaten op de root van een pagina waarop je bent geabonneerd. **/
    SubscriptionReplyRoot = 3,
    /** Als iemand een reactie op je profiel heeft geplaatst. **/
    CommentedOnProfile = 4,
    /** Als je een privébericht hebt. **/
    DirectMessage = 5,
    /** TrialLimits is alleen voor tenant-gebruikers. **/
    TrialLimits = 6,
    /** Als je met @ genoemd bent. **/
    Mentioned = 7
}
interface Notification {
    id: string
    tenantId: string
    /** Bij SSO heeft de user id het formaat `<tenant id>:<user id>`. **/
    userId?: string
    /** Bij gebruik van SSO hoef je je alleen zorgen te maken over `userId`. **/
    anonUserId?: string
    /** urlId is bijna altijd gedefinieerd. Het is alleen optioneel voor notificaties op tenantniveau, die zeldzaam zijn. **/
    urlId?: string
    /** URL wordt gecached voor snelle navigatie naar de bron van de notificatie. **/
    url?: string
    /** Paginatitel wordt gecached voor snelle leesbaarheid van de notificatiebron. **/
    pageTitle?: string
    relatedObjectType: NotificationObjectType
    /** Bijvoorbeeld, comment id. **/
    relatedObjectId: string
    viewed: boolean
    createdAt: string // datumstring
    type: NotificationType
    fromCommentId?: string
    fromVoteId?: string
    /** fromUserName en fromUserAvatarSrc worden hier gecached voor snelle weergave van de notificatie. Ze worden bijgewerkt wanneer de gebruiker wordt bijgewerkt. **/
    fromUserName: string
    fromUserId: string
    fromUserAvatarSrc?: string
    /** Zet dit op true om te stoppen met het ontvangen van notificaties voor dit object. **/
    optedOut?: boolean
}

GET /api/v1/notifications

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

Deze route retourneert maximaal 30 Notification objecten, gesorteerd op createdAt, nieuwste eerst.

U kunt filteren op userId. Bij SSO is de gebruikers-id in het formaat <tenant id>:<user id>.

Ongelezen meldingen voor gebruiker cURL-voorbeeld

Copy

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

Structuur van notificatieverzoek

Copy

interface NotificationsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Pagineren door records over te slaan. **/
    skip?: number
    /** Filteren op gebruiker. **/
    userId?: string
    /** Filteren op urlId. **/
    urlId?: string
    /** Filteren op bronreactie. **/
    fromCommentId?: string
    /** Filteren op gelezen/ongelezen. **/
    viewed?: 'true' | 'false'
    /** Filteren op type. **/
    type?: NotificationType
}

Structuur van het antwoord voor notificaties

Copy

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

GET /api/v1/notifications/count

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

Deze route retourneert een object met het aantal meldingen onder de parameter count.

Het is trager dan /notification-count/ en kost twee keer zoveel credits, maar maakt filteren op meer dimensies mogelijk.

Je kunt filteren op dezelfde parameters als de /notifications endpoint, zoals userId. Bij SSO heeft de gebruikers-id het formaat <tenant id>:<user id>.

Voorbeeld cURL: Aantal ongelezen meldingen voor gebruiker

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'

Voorbeeld cURL: Aantal ongelezen meldingen voor gebruiker op specifieke pagina

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'

Structuur van aanvraag voor meldingsaantal

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Filteren op gebruiker. **/
    userId?: string
    /** Filteren op urlId. **/
    urlId?: string
    /** Filteren op bronreactie. **/
    fromCommentId?: string
    /** Filteren op gelezen/ongelezen. **/
    viewed?: 'true' | 'false'
    /** Filteren op type. **/
    type?: NotificationType
}

Structuur van antwoord voor meldingsaantal

Copy

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

PATCH /api/v1/notifications/:id

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

Dit API-eindpunt maakt het mogelijk om een Notification bij id bij te werken.

Het bijwerken van een Notification heeft de volgende beperkingen:

Je kunt alleen de volgende velden bijwerken:
- viewed
- optedOut

Notification PATCH cURL Voorbeeld

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 Verzoekstructuur

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Notification PATCH Responsstructuur

Copy

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

Pagina-structuur

Een Page-object vertegenwoordigt de pagina waartoe veel opmerkingen kunnen behoren. Deze relatie wordt gedefinieerd door urlId.

Een Page slaat informatie op zoals de paginatitel, het aantal opmerkingen en urlId.

De structuur voor het Page-object is als volgt:

Pagina-structuur

Copy

interface Page {
    id: string
    urlId: string
    url: string
    title?: string
    createdAt: string
    commentCount: number
    rootCommentCount: number
    /** Als dit op null wordt gezet, betekent dit dat alle SSO-gebruikers de pagina kunnen zien. Een lege lijst betekent dat het gesloten is voor alle gebruikers. **/
    accessibleByGroupIds?: string[] | null
    /** Is deze pagina gesloten voor nieuwe opmerkingen? **/
    isClosed?: boolean
}

GET /api/v1/pages

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

Je kunt momenteel alleen alle pagina's ophalen (of een enkele pagina via /by-url-id) die aan je account zijn gekoppeld. Als je fijnmaziger zoeken wilt, neem contact met ons op.

Pages cURL Voorbeeld

Copy

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

Pages Aanvraagstructuur

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Pages Responsstructuur

Copy

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

Handige tip

De Comment API vereist een urlId. Je kunt eerst de Pages API aanroepen om te zien hoe de voor jou beschikbare urlId-waarden eruitzien.

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

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

Individuele pagina's kunnen worden opgehaald met hun bijbehorende urlId. Dit kan handig zijn om paginatitels of het aantal reacties op te zoeken.

cURL-voorbeeld: pagina op basis van URL-ID

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'

Pagina per URL-ID - Aanvraagstructuur

Copy

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

Pagina per URL-ID - Antwoordstructuur

Copy

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

Handige tip

Vergeet niet waarden zoals de urlId te URI-encoderen.

PATCH /api/v1/pages/:id

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

Deze route biedt de mogelijkheid om een enkele Page bij te werken. De bijbehorende reacties worden bijgewerkt.

cURL-voorbeeld voor Pagina-update

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"
}'

Structuur van Pagina-updateverzoek

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Pagina-updateantwoord

Copy

interface PagePatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    user?: Page; // We geven de volledig bijgewerkte pagina terug bij succes.
}

Opmerking

Sommige parameters in het Page-object worden automatisch bijgewerkt. Dit zijn de aantallen en de title-attributen. Aantallen kunnen niet via de API worden bijgewerkt omdat het berekende waarden zijn. De pagina title kan via de API worden ingesteld, maar wordt overschreven als de reactiewidget wordt gebruikt op een pagina met dezelfde urlId en een andere paginatitel.

POST /api/v1/pages

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

Dit API-eindpunt maakt het mogelijk om pagina's aan te maken.

Een veelvoorkomend gebruiksgeval is toegangscontrole.

Opmerkingen:

Als je op een comment-thread hebt gereageerd, of de API hebt aangeroepen om een Comment te maken, heb je al een Page-object aangemaakt! Je kunt proberen het op te halen via de /by-url-id Page-route, door hetzelfde urlId door te geven dat aan de commentaar-widget is doorgegeven.
De Page-structuur bevat enkele berekende waarden. Momenteel zijn dit commentCount en rootCommentCount. Deze worden automatisch gevuld en kunnen niet door de API worden ingesteld. Pogingen daartoe zullen ertoe leiden dat de API een fout teruggeeft.

cURL-voorbeeld voor Page POST

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"]
}'

Structuur van Page POST-aanvraag

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Page POST-respons

Copy

interface PagePostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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';  
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De aangemaakte pagina. **/
    page?: Page
}

DELETE /api/v1/pages/:id

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

Deze route verwijdert een enkele pagina op basis van het id.

Let op dat interactie met de reactie-widget voor een pagina met hetzelfde urlId de Page naadloos opnieuw zal aanmaken.

cURL-voorbeeld voor Paginaverwijdering

Copy

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

Structuur van het verzoek voor pagina-verwijdering

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het antwoord bij pagina-verwijdering

Copy

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

Structuur wachtende webhook-gebeurtenis

Een PendingWebhookEvent-object vertegenwoordigt een webhook-event in de wachtrij dat nog in behandeling is.

PendingWebhookEvent-objecten worden automatisch aangemaakt en kunnen niet handmatig via de API worden aangemaakt. Ze verlopen ook na één jaar. Ze kunnen worden verwijderd, wat de taak uit de wachtrij verwijdert.

Er zijn verschillende eventtypes - controleer eventType (OutboundSyncEventType) en type (OutboundSyncType).

Een veelvoorkomend gebruik van deze API is het implementeren van aangepaste monitoring. U wilt mogelijk periodiek het /count-endpoint aanroepen om het openstaande aantal voor bepaalde filters op te vragen.

De structuur van het PendingWebhookEvent-object is als volgt:

PendingWebhookEvent-structuur

Copy

enum OutboundSyncEventType {
    Create: 0,
    Delete: 1,
    Update: 2
}
enum OutboundSyncType {
    /** WordPress-specifieke synchronisatietaak. **/
    WP: 0,
    Webhook: 1
}
interface PendingWebhookEvent {
    id: string
    /** De comment id die aan het event is gekoppeld. **/
    commentId: string
    /** Het comment-object voor het event op het moment van het event. We zijn begonnen deze toe te voegen in nov 2023. **/
    comment: Comment
    /** Een externe id die mogelijk aan de comment is gekoppeld. **/
    externalId: string | null
    createdAt: Date
    tenantId: string
    attemptCount: number
    /** Ingesteld vóór de eerste poging en na elke mislukking. **/
    nextAttemptAt: Date
    /** Of dit een aanmaak-, verwijder- of update-event is... **/
    eventType: OutboundSyncEventType
    /** Het type synchronisatie dat moet worden uitgevoerd (WordPress, API-aanroep, enz.). **/
    type: OutboundSyncType
    /** Het domein dat overeenkwam met de comment. We gebruiken dit domein om de API-sleutel te kiezen. **/
    domain: string
    /** De laatste fout die optrad. Dit type is niet-getypeerd en is een "dump" van wat er ook is gebeurd. Gewoonlijk bevat het een object met statusCode, body, en een headers-map. **/
    lastError: object | null
}

GET /api/v1/pending-webhook-events

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

Deze route retourneert een lijst met openstaande webhook-events onder de parameter pendingWebhookEvents.

Deze API gebruikt paginering, geleverd door de skip parameter. PendingWebhookEvents worden geretourneerd in pagina's van 100, gesorteerd op createdAt met de nieuwste eerst.

Voorbeeld cURL voor PendingWebhookEvent

Copy

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

Structuur van PendingWebhookEvent-verzoek

Copy

interface PendingWebhookEventsGetQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Zoek naar gebeurtenissen waarvan de pogingentelling groter is dan het opgegeven aantal. **/
    attemptCountGT?: number
}

Structuur van PendingWebhookEvent-respons

Copy

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

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

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

Deze route retourneert een object dat het aantal in behandeling zijnde webhook-events bevat onder de parameter count.

Je kunt filteren op dezelfde parameters als het /pending-webhook-events eindpunt

PendingWebhookEvent Count cURL Voorbeeld

Copy

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

PendingWebhookEvent Count Request Structure

Copy

interface PendingWebhookEventsCountQueryParams {
    tenantId: string
    API_KEY: string
    commentId?: string
    externalId?: string
    eventType?: OutboundSyncEventType
    type?: OutboundSyncType
    domain?: string
    /** Zoek naar events met een aantal pogingen groter dan het opgegeven aantal. **/
    attemptCountGT?: number
}

PendingWebhookEvent Count Response Structure

Copy

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

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

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

Deze route maakt het mogelijk om een enkele PendingWebhookEvent te verwijderen.

Als u een bulkverwijdering moet uitvoeren, roept u de GET-API aan met paginering en roept u vervolgens deze API opeenvolgend aan.

DELETE PendingWebhookEvent cURL Voorbeeld

Copy

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

Structuur van het Delete PendingWebhookEvent-verzoek

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het Delete PendingWebhookEvent-antwoord

Copy

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

Structuur SSO-gebruiker

FastComments biedt een eenvoudig te gebruiken SSO-oplossing. Het bijwerken van de informatie van een gebruiker met de HMAC-gebaseerde integratie is zo eenvoudig als de gebruiker de pagina laten laden met een bijgewerkte payload.

Het kan echter wenselijk zijn om een gebruiker buiten dat proces te beheren, om de consistentie van uw applicatie te verbeteren.

De SSO User API biedt een manier om CRUD-bewerkingen uit te voeren op objecten die we SSOUsers noemen. Deze objecten verschillen van reguliere Users en worden apart gehouden voor typeveiligheid.

De structuur van het SSOUser-object is als volgt:

SSOUser-structuur

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 // Bevoegdheid voor beheerder - SSO-gebruikers met deze vlag worden gefactureerd als SSO-beheerders (apart van reguliere SSO-gebruikers)
    isAdminAdmin?: boolean // Bevoegdheid voor beheerder - SSO-gebruikers met deze vlag worden gefactureerd als SSO-beheerders (apart van reguliere SSO-gebruikers)
    isCommentModeratorAdmin?: boolean // Bevoegdheid voor moderator - SSO-gebruikers met deze vlag worden gefactureerd als SSO-moderators (apart van reguliere SSO-gebruikers)
    /** Als null wordt Access Control niet op de gebruiker toegepast. Als het een lege lijst is, kan deze gebruiker geen pagina's zien of andere gebruikers @mentionen. **/
    groupIds?: string[] | null
    createdFromSimpleSSO?: boolean
    /** Voorkom dat andere gebruikers de activiteit van deze gebruiker, inclusief reacties, op zijn/haar profiel zien. Standaard is true om standaard veilige profielen te bieden. **/
    isProfileActivityPrivate?: boolean
    /** Voorkom dat andere gebruikers reacties plaatsen op het profiel van de gebruiker, of bestaande profielreacties zien. Standaard false. **/
    isProfileCommentsPrivate?: boolean
    /** Voorkom dat andere gebruikers directe berichten naar deze gebruiker sturen. Standaard false. **/
    isProfileDMDisabled?: boolean
    karma?: number
    /** Optionele configuratie voor gebruikersbadges. **/
    badgeConfig?: {
        /** Array met badge-IDs om aan de gebruiker toe te wijzen. Beperkt tot 30 badges. Volgorde wordt gerespecteerd. **/
        badgeIds: string[]
        /** Als true vervangt dit alle bestaande weergegeven badges door de opgegeven. Als false, worden ze toegevoegd aan bestaande badges. **/
        override?: boolean
        /** Als true werkt dit de weergave-eigenschappen van badges bij vanuit de tenantconfiguratie. **/
        update?: boolean
    }
}

Facturering voor SSO-gebruikers

SSO-gebruikers worden anders gefactureerd afhankelijk van hun permissievlaggen:

Reguliere SSO-gebruikers: Gebruikers zonder admin- of moderatorrechten worden gefactureerd als reguliere SSO-gebruikers
SSO-beheerders: Gebruikers met de isAccountOwner of isAdminAdmin vlaggen worden apart gefactureerd als SSO-beheerders (zelfde tarief als reguliere tenantbeheerders)
SSO-moderators: Gebruikers met de isCommentModeratorAdmin vlag worden apart gefactureerd als SSO-moderators (zelfde tarief als reguliere moderators)

Belangrijk: Om dubbele facturatie te voorkomen, dedupliceert het systeem automatisch SSO-gebruikers ten opzichte van reguliere tenantgebruikers en moderators op basis van e-mailadres. Als een SSO-gebruiker hetzelfde e-mailadres heeft als een reguliere tenantgebruiker of moderator, zullen ze niet twee keer gefactureerd worden.

Toegangscontrole

Gebruikers kunnen in groepen worden ingedeeld. Hiervoor is het veld groupIds bedoeld, en het is optioneel.

@Vermeldingen

Standaard zal @mentions username gebruiken om naar andere SSO-gebruikers te zoeken wanneer het @-teken wordt getypt. Als displayName wordt gebruikt, zullen resultaten die overeenkomen met username worden genegeerd wanneer er een match is voor displayName, en zullen de @mention-zoekresultaten displayName gebruiken.

Abonnementen

Met FastComments kunnen gebruikers zich abonneren op een pagina door op het belpictogram in de commentaarwidget te klikken en op Abonneren te klikken.

Bij een reguliere gebruiker sturen we ze notificatie-e-mails op basis van hun notificatie-instellingen.

Bij SSO-gebruikers hebben we dit opgesplitst voor achterwaartse compatibiliteit. Gebruikers zullen deze extra abonnementsmeldingen alleen ontvangen als u optedInSubscriptionNotifications op true zet.

Badges

U kunt badges toewijzen aan SSO-gebruikers met de eigenschap badgeConfig. Badges zijn visuele indicatoren die naast de naam van een gebruiker bij reacties verschijnen.

badgeIds - Een array met badge-IDs om aan de gebruiker toe te wijzen. Deze moeten geldige badge-IDs zijn die in uw FastComments-account zijn aangemaakt. Beperkt tot 30 badges.
override - Als true worden alle bestaande badges die bij reacties worden weergegeven vervangen door de opgegeven badges. Als false of weggelaten, worden de opgegeven badges toegevoegd aan eventuele bestaande badges.
update - Als true worden de weergave-eigenschappen van badges bij elke login van de gebruiker bijgewerkt vanuit de tenantconfiguratie.

GET /api/v1/sso-users

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

Deze route retourneert SSO-gebruikers in pagina's van 100. Paginering wordt geregeld met de parameter skip. Gebruikers worden gesorteerd op hun signUpDate en id.

SSOUsers cURL Voorbeeld

Copy

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

SSOUsers Verzoekstructuur

Copy

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

SSOUsers Responsstructuur

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij een fout. **/
    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

Deze route retourneert een enkele SSO-gebruiker op basis van hun id.

SSOUser per ID cURL-voorbeeld

Copy

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

SSOUser Verzoekstructuur

Copy

interface SSOUserRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Antwoordstructuur

Copy

interface SSOUserByIdResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Opgenomen bij mislukking. **/
    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

Deze route retourneert een enkele SSO-gebruiker op basis van hun e-mailadres.

SSOUser per e-mail cURL-voorbeeld

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 Verzoekstructuur

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser Responsstructuur

Copy

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

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

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

Deze route biedt de mogelijkheid om een enkele SSO-gebruiker bij te werken.

SSOUser bijwerken cURL-voorbeeld

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"
}'

Structuur van SSOUser-bijwerkverzoek

Copy

interface SSOUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** Wanneer e-mail of gebruikersnaam wordt gewijzigd, kunt u dit op 'true' zetten om ook de opmerkingen van de gebruiker bij te werken. Dit verdubbelt de kredietkosten. **/
    updateComments: 'true' | 'false'
}

Structuur van SSOUser-bijwerkrespons

Copy

interface SSOUserPatchResponse {
    status: 'success' | 'failed'
    /** Bij een mislukking opgenomen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-does-not-exist'
    /** Bij een mislukking opgenomen. **/
    reason?: string
    user?: SSOUser; // We geven de volledig bijgewerkte gebruiker terug bij succes.
}

POST /api/v1/sso-users

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

Deze route maakt het mogelijk één SSO-gebruiker aan te maken.

Als u probeert twee gebruikers met hetzelfde ID aan te maken, resulteert dat in een fout.

SSOUser aanmaken cURL-voorbeeld

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"]
}'

In dit voorbeeld specificeren we groupIds voor toegangscontrole, maar dit is optioneel.

SSOUser aanmaken - structuur van de aanvraag

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

SSOUser aanmaken - structuur van het antwoord

Copy

interface SSOUserPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Opgenomen bij mislukking. **/
    reason?: string
    user?: SSOUser; // We geven de aangemaakte gebruiker terug bij succes.
}

Integratie-opmerking

Door de API doorgegeven gegevens kunnen worden overschreven door simpelweg een andere SSO User HMAC-payload mee te geven. Als u bijvoorbeeld een gebruikersnaam instelt via de API, maar bij het SSO-proces bij het laden van de pagina een andere opgeeft, zullen wij hun gebruikersnaam automatisch bijwerken.

We zullen gebruikersparameters in deze flow niet bijwerken tenzij u ze expliciet opgeeft of ze op null zet (niet undefined).

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

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

Deze route biedt de mogelijkheid om een enkele SSO-gebruiker bij te werken.

SSOUser Update cURL-voorbeeld

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"]
}'

In dit voorbeeld geven we groupIds op voor toegangscontrole, maar dit is optioneel.

SSOUser Update Verzoekstructuur

Copy

interface SSOUserPutQueryParams {
    tenantId: string
    API_KEY: string
    /** Wanneer e-mail of gebruikersnaam wordt gewijzigd, kunt u dit op 'true' zetten om ook de opmerkingen van de gebruiker bij te werken. Dit verdubbelt de kredietkosten. **/
    updateComments: 'true' | 'false'
}

SSOUser Update Antwoordstructuur

Copy

interface SSOUserPutResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'invalid-input' | 'missing-id' | 'user-exists'
    /** Opgenomen bij mislukking. **/
    reason?: string
    user?: SSOUser; // We geven de bijgewerkte gebruiker terug bij succes.
}

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

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

Deze route verzorgt het verwijderen van een enkele SSO-gebruiker op basis van hun id.

Let op: het opnieuw laden van de commentaarwidget met een payload voor deze gebruiker zal de gebruiker eenvoudig en naadloos opnieuw aanmaken.

Het verwijderen van de opmerkingen van de gebruiker is mogelijk via de queryparameter deleteComments. Let op: als dit true is:

Alle opmerkingen van de gebruiker worden live verwijderd.
Alle child (nu verweesde) opmerkingen worden verwijderd of geanonimiseerd op basis van de paginaconfiguratie die aan elke opmerking is gekoppeld. Bijvoorbeeld, als de thread deletion mode "anonymize" is, blijven de antwoorden staan en worden de opmerkingen van de gebruiker geanonimiseerd. Dit geldt alleen wanneer commentDeleteMode Remove is (de standaardwaarde).
De creditsCost wordt 2.

Geanonimiseerde opmerkingen

U kunt de opmerkingen van de gebruiker behouden maar eenvoudigweg anonimiseren door commentDeleteMode=1 in te stellen.

Als de opmerkingen van de gebruiker geanonimiseerd worden, worden de volgende waarden op null gezet:

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

isDeleted en isDeletedUser worden op true gezet.

Bij het renderen gebruikt de commentaarwidget DELETED_USER_PLACEHOLDER (standaard: "[deleted]") voor de naam van de gebruiker en DELETED_CONTENT_PLACEHOLDER voor de opmerking. Deze kunnen aangepast worden via de UI voor widgetaanpassing.

Voorbeelden

SSOUser Verwijdering cURL Voorbeeld

Copy

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

Structuur van SSOUser Verwijderingsaanvraag

Copy

enum SSOUserCommentDeleteMode {
    Remove = 0, // standaard
    Anonymize = 1
}
interface SSOUsersDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** U kunt dit op true zetten om ook de opmerkingen van de gebruiker te verwijderen. Dit verdubbelt de creditkosten. **/
    deleteComments?: 'true' | 'false'
    /** U kunt dit instellen om te bepalen hoe met de opmerkingen van de gebruiker wordt omgegaan. **/
    commentDeleteMode?: SSOUserCommentDeleteMode
}

Structuur van SSOUser Verwijderingsantwoord

Copy

interface SSOUsersResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-id' | 'user-does-not-exist'
    /** Opgenomen bij een fout. **/
    reason?: string
    user?: SSOUser; // We geven de verwijderde gebruiker terug bij succes.
}

Abonnementsstructuur

Een Subscription-object vertegenwoordigt een abonnement voor een gebruiker.

Subscription-objecten worden aangemaakt wanneer een gebruiker op de meldingsbel in de reactie-widget klikt en op "Abonneer op deze pagina" klikt.

Abonnementen kunnen ook via de API worden aangemaakt.

Het hebben van een Subscription-object zorgt ervoor dat er Notification-objecten worden gegenereerd en e-mails worden verzonden wanneer er nieuwe reacties worden geplaatst op de root van de bijbehorende pagina waarvoor de Subscription geldt. Het verzenden van e-mails hangt af van het type gebruiker. Voor reguliere gebruikers is dit afhankelijk van optedInNotifications. Voor SSO-gebruikers is dit afhankelijk van optedInSubscriptionNotifications. Let op dat sommige applicaties mogelijk niet het concept van een via het web toegankelijke pagina hebben; in dat geval stelt u eenvoudig urlId in op de id van het item waarop u zich abonneert (dezelfde waarde voor urlId die u aan de reactie-widget zou doorgeven).

De structuur van het Subscription-object is als volgt:

Structuur van Subscription

Copy

interface Subscription {
    id: string
    tenantId: string
    /** Bij SSO is de gebruikers-id in het formaat `<tenant id>:<user id>`. **/
    userId: string
    anonUserId?: string
    urlId: string
    url?: string
    pageTitle?: string
    createdAt: string // datumstring
}

GET /api/v1/subscriptions/:id

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

Deze route retourneert maximaal 30 Subscription-objecten, gesorteerd op createdAt, van nieuw naar oud.

Je kunt filteren op userId. Bij SSO is de gebruikers-id in het formaat <tenant id>:<user id>.

cURL-voorbeeld: abonnementen voor gebruiker

Copy

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

Structuur van het abonnementenverzoek

Copy

interface SubscriptionsGetQueryParams {
    tenantId: string
    API_KEY: string
    /** Pagineren door records over te slaan. **/
    skip?: number
    /** Filter op gebruiker. **/
    userId?: string
}

Structuur van de abonnementenrespons

Copy

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

POST /api/v1/subscriptions

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

Deze API-endpoint maakt het mogelijk een Subscription te creëren. Let op dat een gebruiker slechts één subscription per pagina mag hebben, omdat meer overbodig is, en proberen meer dan één subscription voor dezelfde gebruiker voor dezelfde pagina aan te maken zal resulteren in een fout.

Het aanmaken van een subscription resulteert in het aanmaken van Notification-objecten wanneer een nieuwe comment op de root van de geabonneerde urlId wordt geplaatst (wanneer comment parentId null is).

Subscription POST cURL-voorbeeld

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!"
}'

Structuur van Subscription POST-aanvraag

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Subscription POST-antwoord

Copy

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

DELETE /api/v1/subscriptions/:id

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

Deze route verwijdert een enkel Subscription-object op basis van id.

cURL-voorbeeld voor het verwijderen van Subscription

Copy

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

Structuur van het verzoek voor het verwijderen van Subscription

Copy

interface SubscriptionsDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van de response bij het verwijderen van Subscription

Copy

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

Structuur dagelijks gebruik tenant

Een TenantDailyUsage object represents the usage for a tenant on a given day. If there was no activity for a given tenant on a given day, that day will not have a TenantDailyUsage object.

The TenantDailyUsage object is not real time and may be minutes behind actual usage.

The structure for the TenantDailyUsage object is as follows:

Structuur van TenantDailyUsage

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
    /** Genegeerd voor facturering. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

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

Deze route maakt het mogelijk om het gebruik van een tenant te doorzoeken op jaar, maand en dag. Er kunnen maximaal 365 objecten worden geretourneerd, en de kosten zijn 1 API-credit per 10 objecten.

Response-objecten worden gesorteerd op de datum waarop ze zijn aangemaakt (de oudste eerst).

TenantDailyUsage cURL-zoekvoorbeeld

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 Verzoekstructuur

Copy

interface TenantDailyUsageQueryParams {
    tenantId: string
    API_KEY: string
    /** Gebaseerd op UTC. **/
    yearNumber?: number
    /** Op 0 gebaseerd. Gebaseerd op UTC. **/
    monthNumber?: number
    /** Op 1 gebaseerd. Gebaseerd op UTC. **/
    dayNumber?: number
}

TenantDailyUsage Responsstructuur

Copy

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

Tenantstructuur

De Tenant definieert een FastComments.com-klant. Ze kunnen via de API worden aangemaakt door tenants met white-labeling toegang. White-labeled tenants kunnen geen andere white-labeled tenants aanmaken (er is slechts één niveau van nesting toegestaan).

De structuur voor het Tenant-object is als volgt:

Tenant-structuur

Copy

export enum SiteType {
    Unknown = 0,
    WordPress = 1
}
/** Dit kan ook via de DomainConfig API worden afgehandeld. **/
export interface TenantDomainConfig {
    domain: string
    emailFromName?: string
    emailFromEmail?: string
    createdAt?: string,
    siteType?: FastCommentsSiteType, // je wilt waarschijnlijk Unknown
    logoSrc?: string, // pad naar ruwe afbeelding
    logoSrc100px?: string, // verkleind voor miniaturen
    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 vanwege "legacy" redenen
    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 - Wordt berekend op basis van packageId. **/
    hasFlexPricing?: boolean
    /** @readonly **/
    flexLastBilledAmount?: number
    /** @readonly - Wordt berekend op basis van packageId. **/
    hasAuditing?: boolean
    /** Je kunt een sleutel-waarde-paar opslaan bij de tenant dat je kunt gebruiken om te zoeken. Sleutels mogen geen "." of "$" bevatten, of langer zijn dan 100 tekens. Waarden mogen niet langer zijn dan 2k tekens. **/
    meta?: Record<string, string | null>
}

GET /api/v1/tenants/:id

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

Deze route retourneert een enkele Tenant op basis van id.

cURL-voorbeeld: Tenant per ID

Copy

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

Structuur van Tenant-verzoek

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Tenant-respons

Copy

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

GET /api/v1/tenants

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

Deze API retourneert tenants die door uw tenant worden beheerd.

Paginering wordt verzorgd door de queryparameter skip. Tenants worden geretourneerd in pagina's van 100, gesorteerd op signUpDate en id.

De kosten zijn gebaseerd op het aantal geretourneerde tenants; het kost 1 credit per 10 geretourneerde tenants.

Tenant cURL Voorbeeld

Copy

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

U kunt meta-parameters definiëren op de Tenant-objecten en zoeken naar overeenkomende tenants. Bijvoorbeeld, voor de sleutel someKey en de meta-waarde some-value, kunnen we een JSON-object met deze sleutel/waarde maken en vervolgens URI-encoden als queryparameter om te filteren:

Tenant Query op Meta cURL Voorbeeld

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 Request-structuur

Copy

interface TenantsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Het aantal tenants om over te slaan voor paginering. **/
    skip?: number
    /** Filteren op meta-parameters. **/
    meta?: string
}

Tenant Response-structuur

Copy

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

POST /api/v1/tenants

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

Deze route biedt de mogelijkheid om een enkele Tenant toe te voegen.

Het aanmaken van een Tenant kent de volgende beperkingen:

Een name is verplicht.
domainConfiguration is verplicht.
De volgende waarden mogen niet worden meegegeven bij het aanmaken van een Tenant:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
De signUpDate mag niet in de toekomst liggen.
De name mag niet langer zijn dan 200 characters.
De email mag niet langer zijn dan 300 characters.
De email moet uniek zijn over alle FastComments.com tenants.
U mag geen tenants aanmaken als de parent tenant geen geldige TenantPackage heeft gedefinieerd.
- Als uw tenant via FastComments.com is aangemaakt, zou dit geen probleem moeten zijn.
U mag niet meer tenants aanmaken dan gedefinieerd onder maxWhiteLabeledTenants in uw package.
U moet de queryparameter tenantId opgeven, dit is de id van uw parent tenant met white labeling ingeschakeld.

We kunnen een Tenant aanmaken met slechts een paar parameters:

Voorbeeld cURL-aanvraag voor Tenant

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" } ]
}'

Structuur van Tenant-aanmaakverzoek

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Tenant-aanmaakrespons

Copy

interface TenantPostResponse {
    status: 'success' | 'failed'
    /** Inbegrepen bij mislukking. **/
    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'
    /** Inbegrepen bij mislukking. **/
    reason?: string
    tenant?: Tenant; // We geven de volledig aangemaakte tenant terug bij succes.
}

PATCH /api/v1/tenants/:id

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

Dit API-eindpunt maakt het mogelijk een Tenant op basis van id bij te werken.

Het bijwerken van een Tenant heeft de volgende beperkingen:

De volgende waarden mogen niet worden bijgewerkt:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
- managedByTenantId
De signUpDate mag niet in de toekomst liggen.
De name mag niet langer zijn dan 200 characters.
De email mag niet langer zijn dan 300 characters.
De email moet uniek zijn voor alle tenants van FastComments.com.
Wanneer billingInfoValid op true wordt gezet, moet billingInfo in hetzelfde verzoek worden meegegeven.
U mag de packageId die aan uw eigen tenant is gekoppeld niet bijwerken.
U mag de paymentFrequency die aan uw eigen tenant is gekoppeld niet bijwerken.

Tenant PATCH cURL Voorbeeld

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 Aanvraagstructuur

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Tenant PATCH Antwoordstructuur

Copy

interface TenantPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'; 
    /** Opgenomen bij mislukking. **/
    reason?: string
}

DELETE /api/v1/tenants/:id

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

Deze route zorgt voor het verwijderen van een Tenant en alle bijbehorende gegevens (gebruikers, reacties, etc.) op basis van id.

De volgende beperkingen gelden bij het verwijderen van tenants:

De tenant moet van uzelf zijn, of een white-labeled tenant die u beheert.
De queryparameter sure moet op true worden gezet.

Voorbeeld cURL-verzoek voor tenantverwijdering

Copy

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

Structuur van verzoek voor tenantverwijdering

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van het antwoord voor tenantverwijdering

Copy

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

Structuur tenantpakket

De TenantPackage definieert pakketinformatie die beschikbaar is voor een Tenant. Een tenant kan meerdere pakketten beschikbaar hebben, maar slechts één tegelijk in gebruik.

Een Tenant kan niet voor producten worden gebruikt totdat zijn packageId naar een geldige TenantPackage verwijst.

Er zijn twee soorten TenantPackage-objecten:

Pakketten met vaste prijs - waarbij hasFlexPricing false is.
Flexibele prijsstelling - waarbij hasFlexPricing true is.

In beide gevallen worden limieten gedefinieerd op het account dat het pakket gebruikt, maar bij Flex wordt de tenant een basisprijs in rekening gebracht plus wat ze gebruikt hebben, gedefinieerd door de flex* parameters.

Een tenant kan meerdere tenant-pakketten hebben en kan het pakket zelf wijzigen vanaf de Pagina met facturatiegegevens.

Als u zelf de facturering voor tenants afhandelt, moet u nog steeds voor elke tenant een pakket definiëren om hun limieten vast te leggen. Stel eenvoudig billingHandledExternally in op true op de Tenant en zij zullen hun facturatiegegevens of actieve pakket niet zelf kunnen wijzigen.

U mag geen pakketten aanmaken met hogere limieten dan de bovenliggende tenant.

De structuur van het TenantPackage-object is als volgt:

Structuur van TenantPackage

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 // Kosten per reguliere SSO-gebruiker (zonder admin/moderatorrechten)
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexSSOAdminCostCents?: null // Kosten per SSO-gebruiker met admin-rechten (isAccountOwner or isAdminAdmin flags)
    flexSSOAdminUnit?: null
    flexSSOModeratorCostCents?: null // Kosten per SSO-gebruiker met moderatorrechten (isCommentModeratorAdmin flag)
    flexSSOModeratorUnit?: null
    flexMinimumCostCents?: null
}

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

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

Deze route retourneert een enkel Tenant Package op basis van id.

TenantPackage per ID cURL-voorbeeld

Copy

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

Structuur van TenantPackage-verzoek

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van TenantPackage-antwoord

Copy

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

GET /api/v1/tenant-packages

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

Deze API gebruikt paginering, geleverd via de queryparameter skip. TenantPackages worden in pagina's van 100 teruggegeven, gesorteerd op createdAt en id.

De kosten zijn gebaseerd op het aantal geretourneerde tenant packages: 1 credit per 10 tenant packages.

TenantPackage cURL Voorbeeld

Copy

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

TenantPackage Verzoekstructuur

Copy

interface TenantPackagesRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Het aantal tenant packages om over te slaan voor paginering. **/
    skip?: number
}

TenantPackage Responsstructuur

Copy

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

POST /api/v1/tenant-packages

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

Deze route biedt de mogelijkheid om een enkele TenantPackage toe te voegen.

Het aanmaken van een TenantPackage kent de volgende beperkingen:

De volgende parameters zijn verplicht:
- name
- tenantId
- monthlyCostUSD - Can be null.
- yearlyCostUSD - Can be null.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - If true, then all flex* parameters are required.
De name mag niet langer zijn dan 50 characters.
Elk forWhoText item mag niet langer zijn dan 200 characters.
Elk featureTaglines item mag niet langer zijn dan 100 characters.
De TenantPackage moet "kleiner" zijn dan de parent tenant. Bijvoorbeeld, alle max* parameters moeten lagere waarden hebben dan de parent tenant.
Een white-labeled tenant mag maximaal vijf pakketten hebben.
Alleen tenants met toegang tot white labeling mogen een TenantPackage aanmaken.
Je mag geen pakketten toevoegen aan je eigen tenant. :)

We kunnen een TenantPackage als volgt aanmaken:

TenantPackage aanmaken via e-mail cURL-voorbeeld

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 aanmaken - verzoekstructuur

Copy

interface TenantPackagePostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage aanmaken - responsstructuur

Copy

interface TenantPackagePostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    tenantPackage?: TenantPackage; // We geven het volledig aangemaakte tenantpakket terug bij succes.
}

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

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

Deze API-endpoint biedt de mogelijkheid om een TenantPackage op basis van id bij te werken.

Het bijwerken van een TenantPackage kent de volgende beperkingen:

Als u hasFlexPricing op true zet, dan zijn alle flex*-parameters vereist in datzelfde verzoek.
De name mag niet langer zijn dan 50 characters.
Elk forWhoText-item mag niet langer zijn dan 200 characters.
Elk featureTaglines-item mag niet langer zijn dan 100 characters.
De TenantPackage moet "kleiner" zijn dan de bovenliggende tenant. Bijvoorbeeld moeten alle max*-parameters lagere waarden hebben dan de bovenliggende tenant.
U mag de tenantId die aan een TenantPackage is gekoppeld niet wijzigen.

TenantPackage PATCH cURL Voorbeeld

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 Verzoekstructuur

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

TenantPackage PATCH Responsstructuur

Copy

interface TenantPackagePatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'; 
    /** Opgenomen bij mislukking. **/
    reason?: string
}

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

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

Deze route verzorgt het verwijderen van een TenantPackage op basis van het id.

U mag geen TenantPackage verwijderen die in gebruik is (de packageId van een tenant verwijst naar het pakket). Werk eerst de Tenant bij.

Voorbeeld cURL-verzoek voor TenantPackage-verwijdering

Copy

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

Structuur van TenantPackage-verwijderingsverzoek

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van TenantPackage-verwijderingsantwoord

Copy

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

Structuur tenantgebruiker

De TenantUser definieert een User die wordt beheerd door een specifieke tenant. Hun account staat volledig onder controle van de tenant waarmee ze zijn geassocieerd, en hun account kan worden bijgewerkt of verwijderd via de UI of de API.

Tenantgebruikers kunnen beheerders zijn met alle rechten en toegang tot de Tenant, of ze kunnen beperkt zijn tot specifieke rechten om opmerkingen te modereren, toegang te krijgen tot API-sleutels, enz.

De structuur voor het TenantUser-object is als volgt:

Structuur van TenantUser

Copy

/** Dit is voor meldingen. **/
export enum UserDigestEmailFrequency {
    Disabled = -1,
    Daily = 0,
    Weekly = 1,
    Monthly = 2
}
export interface TenantUser {
    id: string
    tenantId: string
    username: string
    /** Een link naar de blog van de reageerder, bijvoorbeeld. **/
    websiteUrl?: string
    email: string
    signUpDate: number
    createdFromUrlId: string
    createdFromTenantId: string
    verified: boolean
    loginCount: number
    optedInNotifications: boolean
    optedInTenantNotifications: boolean
    hideAccountCode: boolean
    avatarSrc?: string
    /** Ontvangt de gebruiker hulpverzoeken van reageerders? **/
    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

Deze route retourneert een enkele TenantUser op basis van id.

TenantUser per ID cURL-voorbeeld

Copy

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

Structuur van TenantUser-verzoek

Copy

interface TenantUserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van TenantUser-respons

Copy

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

GET /api/v1/tenant-users

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

Deze API gebruikt paginering, geleverd door de skip queryparameter. TenantUsers worden geretourneerd in pagina's van 100, gesorteerd op signUpDate, username en id.

De kosten zijn gebaseerd op het aantal TenantUsers dat wordt geretourneerd; de kosten zijn 1 credit per 10 geretourneerde TenantUsers.

TenantUser cURL Voorbeeld

Copy

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

TenantUser Aanvraagstructuur

Copy

interface TenantUsersRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Het aantal TenantUsers om over te slaan voor paginering. **/
    skip?: number
}

TenantUser Responsstructuur

Copy

interface TenantUsersResponse {
    status: 'success' | 'failed'
    /** Wordt opgenomen bij een fout. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Wordt opgenomen bij een fout. **/
    reason?: string
    tenantUsers?: TenantUser[]
}

POST /api/v1/tenant-users

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

Deze route biedt de mogelijkheid om één TenantUser toe te voegen.

Het aanmaken van een TenantUser heeft de volgende beperkingen:

Een username is verplicht.
Een email is verplicht.
De signUpDate mag niet in de toekomst liggen.
De locale moet voorkomen in de lijst met Ondersteunde Locales.
De username moet uniek zijn op heel FastComments.com. Als dit een probleem is, raden we aan in plaats daarvan SSO te gebruiken.
De email moet uniek zijn op heel FastComments.com. Als dit een probleem is, raden we aan in plaats daarvan SSO te gebruiken.
U mag niet meer tenant users aanmaken dan gedefinieerd onder maxTenantUsers in uw pakket.

We kunnen een TenantUser als volgt aanmaken

TenantUser Aanmaken cURL Voorbeeld

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 Aanmaak Requeststructuur

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Aanmaak Responsstructuur

Copy

interface TenantUserPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    tenantUser?: TenantUser; // We geven de volledig aangemaakte TenantUser terug bij succes.
}

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

Deze route biedt de mogelijkheid om een aanmeldlink te verzenden naar een enkele TenantUser.

Handig bij het batchgewijs aanmaken van gebruikers, zodat je ze niet hoeft uit te leggen hoe ze kunnen inloggen op FastComments.com. Dit stuurt hen eenvoudig een "magische link" om in te loggen die vervalt na 30 days.

De volgende beperkingen gelden voor het verzenden van een aanmeldlink naar een TenantUser:

De TenantUser moet al bestaan.
Je moet toegang hebben om de Tenant te beheren waartoe de TenantUser behoort.

We kunnen een aanmeldlink naar een TenantUser verzenden als volgt:

TenantUser Login Link cURL Voorbeeld

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'

Dit zal een e-mail sturen zoals Bob at TenantName is inviting you to be a moderator...

TenantUser Login Link Verzoekstructuur

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

TenantUser Login Link Antwoordstructuur

Copy

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

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

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

Deze route biedt de mogelijkheid om een enkele TenantUser bij te werken.

Het bijwerken van een TenantUser heeft de volgende beperkingen:

De signUpDate mag niet in de toekomst liggen.
De locale moet in de lijst van Ondersteunde locales staan.
De username moet uniek zijn op heel FastComments.com. Als dit een probleem is, raden we aan in plaats daarvan SSO te gebruiken.
De email moet uniek zijn op heel FastComments.com. Als dit een probleem is, raden we aan in plaats daarvan SSO te gebruiken.
U kunt de tenantId van een gebruiker niet bijwerken.

We kunnen een TenantUser als volgt aanmaken

TenantUser Update cURL Voorbeeld

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 Update Verzoekstructuur

Copy

interface TenantUserPatchQueryParams {
    tenantId: string
    API_KEY: string
    /** Wanneer e-mail of gebruikersnaam wordt gewijzigd, kunt u dit op 'true' zetten om ook de opmerkingen van de gebruiker bij te werken. Dit verdubbelt de kredietkosten. **/
    updateComments: 'true' | 'false'
}

TenantUser Update Responsestructuur

Copy

interface TenantUserPatchResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
}

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

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

Deze route maakt het mogelijk om een TenantUser te verwijderen op basis van id.

Het is mogelijk om de opmerkingen van de gebruiker te verwijderen via de queryparameter deleteComments. Let op dat wanneer dit waar is:

Alle opmerkingen van de gebruiker worden direct verwijderd.
Alle child (nu wees) opmerkingen worden verwijderd of geanonimiseerd op basis van de pagina-configuratie die aan elke opmerking is gekoppeld. Bijvoorbeeld, als thread deletion mode "anonymize" is, blijven reacties behouden en worden de opmerkingen van de gebruiker geanonimiseerd. Dit geldt alleen wanneer commentDeleteMode Remove is (de standaardwaarde).
De creditsCost wordt 2.

Geanonimiseerde opmerkingen

U kunt de opmerkingen van de gebruiker behouden maar eenvoudigweg anonimiseren door commentDeleteMode=1 in te stellen.

Als de opmerkingen van de gebruiker geanonimiseerd worden, worden de volgende waarden op null gezet:

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

isDeleted en isDeletedUser worden ingesteld op true.

Bij weergave zal de comment-widget DELETED_USER_PLACEHOLDER (standaard: "[deleted]") gebruiken voor de naam van de gebruiker en DELETED_CONTENT_PLACEHOLDER voor de opmerking. Deze kunnen worden aangepast via de Widget Customization UI.

Voorbeelden

cURL-voorbeeld voor TenantUser-verwijdering

Copy

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

Structuur van TenantUser-verwijderverzoek

Copy

enum TenantUserCommentDeleteMode {
    Remove = 0, // standaard
    Anonymize = 1
}
interface TenantUserDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** U kunt dit op true zetten om ook de opmerkingen van de gebruiker te verwijderen. Dit verdubbelt de kosten in credits. **/
    deleteComments?: 'true' | 'false'
    /** U kunt dit instellen om te bepalen hoe met de opmerkingen van de gebruiker om te gaan. **/
    commentDeleteMode?: TenantUserCommentDeleteMode
}

Structuur van TenantUser-verwijderingsantwoord

Copy

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

Gebruikersstructuur

User is een object dat het meest voorkomende gemeenschappelijke kenmerk van alle gebruikers vertegenwoordigt.

Houd er rekening mee dat we bij FastComments verschillende gebruikssituaties voor gebruikers hebben:

Secure SSO
Simple SSO
Tenant Users (For example: Administrators)
Commenters

Deze API is voor Commenters en gebruikers die via Simple SSO zijn aangemaakt. In feite kan elke gebruiker die via uw site is aangemaakt via deze API worden benaderd. Tenant Users kunnen ook op deze manier worden opgehaald, maar u krijgt meer informatie door te werken met de /tenant-users/ API.

Gebruik voor Secure SSO de /sso-users/ API.

U kunt deze soorten gebruikers niet bijwerken. Ze hebben hun account via uw site aangemaakt, dus we bieden beperkte alleen-lezen toegang, maar u kunt geen wijzigingen aanbrengen. Als u dit soort flow wilt hebben, moet u Secure SSO instellen.

De structuur van het User-object is als volgt:

Structuur van User

Copy

export interface User {
    /** Dit is tevens de id die als userId wordt gebruikt op commentaarobjecten. **/
    id: string
    username: string
    /** Een link naar bijvoorbeeld de blog van de commenter. **/
    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

Deze route retourneert een enkele gebruiker op basis van id.

cURL-voorbeeld voor gebruiker per id

Copy

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

Structuur van gebruikersverzoek

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van antwoord voor gebruiker

Copy

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

Stemstructuur

Een Vote-object vertegenwoordigt een door een gebruiker achtergelaten stem.

De relatie tussen reacties en stemmen wordt gedefinieerd via commentId.

De structuur voor het Vote-object is als volgt:

Structuur van Vote

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

Stemmen moeten worden opgehaald via urlId.

Soorten stemmen

Er zijn drie soorten stemmen:

Geauthenticeerde stemmen, die worden toegepast op de bijbehorende opmerking. Je kunt deze via deze API aanmaken.
Geauthenticeerde stemmen, die in afwachting zijn van verificatie, en dus nog niet op de opmerking worden toegepast. Deze worden aangemaakt wanneer een gebruiker het FastComments.com inloggen om te stemmen-mechanisme gebruikt.
Anonieme stemmen, die worden toegepast op de bijbehorende opmerking. Deze worden aangemaakt samen met anoniem reageren.

Deze worden in afzonderlijke lijsten in de API teruggegeven om verwarring te verminderen.

Voorbeeld cURL-aanvraag

Copy

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

Structuur van de Votes-aanvraag

Copy

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

Structuur van de Votes-respons

Copy

interface VotesResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij falen. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id'
    /** Opgenomen bij falen. **/
    reason?: string
    /** Geautoriseerde, geverifieerde stemmen, toegepast op hun bijbehorende opmerkingen. **/
    appliedAuthorizedVotes: Vote[]
    /** Anonieme stemmen, toegepast op hun bijbehorende opmerkingen. **/
    appliedAnonymousVotes: Vote[]
    /** Stemmen in afwachting van verificatie, nog niet toegepast op hun bijbehorende opmerkingen. **/
    pendingVotes: Vote[]
}

Opmerkingen over anonieme stemmen

Let op dat anonieme stemmen die via deze API zijn aangemaakt, verschijnen in de lijst appliedAuthorizedVotes. Ze worden als geautoriseerd beschouwd omdat ze via de API met een API key zijn aangemaakt.

De structuur appliedAnonymousVotes is voor stemmen die zijn aangemaakt zonder e-mail, API key, enz.

GET /api/v1/votes/for-user

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

Maakt het mogelijk om stemmen op te halen die een gebruiker heeft achtergelaten voor een bepaalde urlId. Vereist een userId dat een FastComments.com- of een SSO User-account kan zijn.

Dit is handig als je wilt laten zien of een gebruiker op een reactie heeft gestemd. Wanneer je reacties ophaalt, roep je simpelweg deze API tegelijkertijd aan voor de gebruiker met dezelfde urlId.

Als je anoniem stemmen gebruikt, geef je in plaats daarvan anonUserId mee.

Stemmen voor gebruiker cURL Voorbeeld

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'

Stemmen voor anonieme gebruiker cURL Voorbeeld

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'

Let op dat anonieme stemmen zullen verschijnen in de appliedAuthorizedVotes lijst. Ze worden als geautoriseerd beschouwd omdat ze via de API met een API key zijn aangemaakt.

Verzoekstructuur: Stemmen voor gebruiker

Copy

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

Antwoordstructuur: Stemmen voor gebruiker

Copy

interface VotesForUserResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'invalid-user-id'
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** Geautoriseerde, geverifieerde stemmen, toegepast op hun overeenkomstige reacties. **/
    appliedAuthorizedVotes: Vote[]
    /** Stemmen in afwachting van verificatie, nog niet toegepast op hun overeenkomstige reacties. **/
    pendingVotes: Vote[]
}

POST /api/v1/votes

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

Deze route biedt de mogelijkheid om één geautoriseerde Vote toe te voegen. Votes kunnen up (+1) of down (-1) zijn.

Voorbeeld cURL-verzoek voor het aanmaken van een stem

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'

Voorbeeld cURL-verzoek voor het aanmaken van een anonieme stem

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'

Structuur van het verzoek voor het aanmaken van een stem

Copy

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

Structuur van de respons voor het aanmaken van een stem

Copy

interface VotePostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    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'
    /** Opgenomen bij een fout. **/
    reason?: string
    voteId?: string
}

Creating Anonymous Votes

Anonieme stemmen kunnen worden aangemaakt door anonUserId in de queryparameters te zetten in plaats van userId.

Deze id hoeft nergens overeen te komen met een gebruikersobject (vandaar anoniem). Het is simpelweg een identificator voor de sessie, zodat je stemmen opnieuw kunt ophalen in dezelfde sessie, om te controleren of op een reactie is gestemd.

Als je niet zoiets hebt als "anonymous sessions" zoals FastComments - je kunt dit eenvoudig instellen op een willekeurige ID, zoals een UUID (hoewel we kleinere identificatoren waarderen om ruimte te besparen).

Other Notes

Deze API houdt zich aan tenant-niveau instellingen. Bijvoorbeeld, als je stemmen uitschakelt voor een bepaalde pagina, en je probeert via de API een stem aan te maken, zal dit falen met foutcode voting-disabled.
Deze API is standaard actief.
Deze API zal de votes van de overeenkomstige Comment bijwerken.

DELETE /api/v1/votes/:id

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

Deze route biedt de mogelijkheid om een enkele Vote te verwijderen.

Voorbeeld cURL-verzoek voor Vote verwijderen

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'

Structuur van het Vote-verwijderingsverzoek

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van Vote Delete-respons

Copy

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

Opmerkingen:

Deze API respecteert instellingen op tenant-niveau. Bijvoorbeeld, als je stemmen uitschakelt voor een bepaalde pagina en je via de API probeert een stem te maken, zal dit mislukken met foutcode voting-disabled.
Deze API is standaard actief.
Deze API zal de votes van de overeenkomstige Comment bijwerken.

Structuur domeinconfiguratie

Een DomainConfig-object vertegenwoordigt de configuratie voor een domein van een tenant.

De structuur voor het DomainConfig-object is als volgt:

Structuur van Domain Config

Copy

interface DomainConfig {
    /** Een domein, geen URL, zoals "fastcomments.com" of "www.example.com". Subdomein kan worden opgenomen als beperking tot een subdomein gewenst is. Maximaal 1000 tekens. **/
    domain: string
    /** De afzendernaam die gebruikt wordt bij het verzenden van e-mails. **/
    emailFromName?: string
    /** Het From-Email-adres dat wordt gebruikt bij het verzenden van e-mails. Zorg dat SPF is ingesteld om mail.fastcomments.com toe te staan e-mails te verzenden namens het domein dat in dit attribuut wordt gebruikt. **/
    emailFromEmail?: string
    /** ALLEEN-LEZEN. Wanneer het object is aangemaakt. **/
    createdAt: string
    /** Het logo dat bij dit domein hoort. Gebruikt in e-mails. Gebruik HTTPS. **/
    logoSrc?: string
    /** Een kleiner logo dat bij dit domein hoort. Gebruik HTTPS. **/
    logoSrc100px?: string
    /** ALLEEN SSO. De URL die wordt gebruikt in de voettekst van elke verzonden e-mail. Ondersteunt een "[userId]"-variabele. **/
    footerUnsubscribeURL?: string
    /** ALLEEN SSO. De headers die in elke verzonden e-mail worden gebruikt. Handig bijvoorbeeld voor het instellen van unsubscribe-gerelateerde headers om de bezorging te verbeteren. De List-Unsubscribe-vermelding in dit Record, indien aanwezig, ondersteunt een "[userId]"-variabele. **/
    emailHeaders?: Record<string, string>
    /** Schakel alle afmeldlinks uit. Niet aanbevolen, kan de bezorgingspercentages schaden. **/
    disableUnsubscribeLinks?: boolean
    /** DKIM-configuratie. **/
    dkim?: DomainConfigDKIM
}

Structuur van DKIM-configuratie

Copy

interface DomainConfigDKIM {
    /** De domeinnaam in uw DKIM-record. **/
    domainName: string
    /** De DKIM-sleutelselector die gebruikt moet worden. **/
    keySelector: string
    /** Uw privésleutel. Begint met -----BEGIN PRIVATE KEY----- en eindigt met -----END PRIVATE KEY----- **/
    privateKey: string
}

Voor authenticatie

Domeinconfiguratie wordt gebruikt om te bepalen welke sites de FastComments-widget voor uw account kunnen hosten. Dit is een basale vorm van authenticatie, wat betekent dat het toevoegen of verwijderen van domeinconfiguraties de beschikbaarheid van uw FastComments-installatie in productie kan beïnvloeden.

Verwijder of werk de domain-eigenschap van een Domain Config voor een domein dat momenteel in gebruik is niet bij, tenzij het de bedoeling is dat dat domein wordt uitgeschakeld.

Dit heeft hetzelfde gedrag als het verwijderen van een domein via /auth/my-account/configure-domains.

Let ook op dat het verwijderen van een domein uit de My Domains-interface alle overeenkomstige configuratie voor dat domein verwijdert die mogelijk via deze interface is toegevoegd.

Voor e-mailaanpassing

De afmeldlink in de e-mailvoettekst en de één-klik-afmelden-functie die door veel e-mailclients wordt aangeboden, kunnen via deze API worden geconfigureerd door respectievelijk footerUnsubscribeURL en emailHeaders te definiëren.

Voor DKIM

Nadat u uw DKIM DNS-records hebt gedefinieerd, werkt u eenvoudig de DomainConfig bij met uw DKIM-configuratie met behulp van de opgegeven structuur.

GET /api/v1/domain-configs

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

Deze API maakt het mogelijk om alle DomainConfig objecten voor een tenant op te halen.

DomainConfig GET cURL Voorbeeld

Copy

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

DomainConfig GET Verzoekstructuur

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig GET Responsstructuur

Copy

interface GetDomainConfigsResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key'
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De configuraties! **/
    configurations: DomainConfig[] | null
}

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

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

Individuele DomainConfigs kunnen worden opgehaald via hun overeenkomstige domain.

Domain Config per domein cURL Voorbeeld

Copy

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

Domain Config per domein Aanvraagstructuur

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Domain Config per domein Responsstructuur

Copy

interface DomainConfigResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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'
    /** Opgenomen bij mislukking. **/
    reason?: string
    configuration?: DomainConfig | null
}

POST /api/v1/domain-configs

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

Dit API-eindpunt biedt de mogelijkheid om domeinconfiguraties aan te maken.

Het toevoegen van een configuratie voor een domein machtigt dat domein voor het FastComments-account.

Veelvoorkomende gebruikssituaties voor deze API zijn de initiële installatie, wanneer veel domeinen toegevoegd moeten worden, of aangepaste configuratie voor het verzenden van e-mails.

DomainConfig POST cURL Voorbeeld

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 Verzoekstructuur

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig POST Responsstructuur

Copy

interface DomainConfigPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    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';  
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** De aangemaakte configuratie. **/
    configuration?: DomainConfig
}

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

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

Dit API-eindpunt biedt de mogelijkheid om een domeinconfiguratie bij te werken door alleen het domein en het attribuut dat moet worden bijgewerkt op te geven.

DomainConfig PATCH cURL Voorbeeld

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 Verzoekstructuur

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PATCH Responsstructuur

Copy

interface DomainConfigPatchResponse {
    status: 'success' | 'failed'
    /** Wordt opgenomen bij een fout. **/
    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';  
    /** Wordt opgenomen bij een fout. **/
    reason?: string
    /** De bijgewerkte configuratie. **/
    configuration?: DomainConfig
}

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

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

Dit API-eindpunt biedt de mogelijkheid om een domeinconfiguratie te vervangen.

DomainConfig PUT cURL Voorbeeld

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 Verzoekstructuur

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

DomainConfig PUT Antwoordstructuur

Copy

interface DomainConfigPutResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een fout. **/
    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';  
    /** Opgenomen bij een fout. **/
    reason?: string
    /** De bijgewerkte configuratie. **/
    configuration?: DomainConfig
}

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

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

Deze route biedt het verwijderen van een enkele DomainConfig op basis van id.

Opmerking: Het verwijderen van een DomainConfig zal dat domein niet langer machtigen om FastComments te gebruiken.
Opmerking: Het opnieuw toevoegen van een domein via de UI zal het object opnieuw aanmaken (met alleen domain ingevuld).

Voorbeeld cURL-verzoek voor DomainConfig-verwijdering

Copy

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

Structuur van DomainConfig-verwijderingsverzoek

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van DomainConfig-verwijderingsantwoord

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
}

Structuur vraagconfiguratie

FastComments biedt een manier om vragen te maken en de resultaten ervan te aggregeren. Een voorbeeld van een vraag (hierna aangeduid als QuestionConfig) kan een sterrenbeoordeling, een schuifregelaar of een NPS-vraag zijn (bepaald via type).

Vraaggegevens kunnen individueel, gezamenlijk, over de tijd, in totaal, per pagina, enzovoort worden geaggregeerd.

Het framework bevat alle mogelijkheden die nodig zijn om client-side widgets (met uw server voor deze API), beheerdersdashboards en rapportagetools te bouwen.

Eerst moeten we een QuestionConfig definiëren. De structuur is als volgt:

Structuur van QuestionConfig

Copy

type QuestionConfigType = 'nps' | 'slider' | 'star' | 'thumbs';
interface QuestionConfig {
    id: string
    tenantId: string
    name: string
    question: string
    helpText?: string
    createdAt: string
    createdBy: string
    /** ALLEEN LEZEN - wordt verhoogd voor elk nieuw antwoord. **/
    usedCount: number
    /** Een datumstring die aangeeft wanneer de configuratie voor het laatst is gebruikt (wanneer er een resultaat is achtergelaten). **/
    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

Deze route retourneert tot 100 QuestionConfig-objecten tegelijk, gepagineerd. De kosten zijn 1 per 100 objecten. Ze worden gesorteerd op oplopende vraagtekst (veld question).

Voorbeeld van QuestionConfig

Copy

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

QuestionConfig Verzoekstructuur

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
    /** Voor paginering. Begint bij 0. **/
    skip?: number
}

QuestionConfig Responsstructuur

Copy

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

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

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

Deze route retourneert een enkele QuestionConfig op basis van zijn id.

QuestionConfig per ID cURL-voorbeeld

Copy

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

QuestionConfig verzoekstructuur

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig antwoordstructuur

Copy

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

POST /api/v1/question-configs

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

Dit API-endpoint biedt de mogelijkheid om een QuestionConfig aan te maken.

QuestionConfig POST cURL-voorbeeld

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 verzoekstructuur

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig POST antwoordstructuur

Copy

interface QuestionConfigPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';  
    /** Opgenomen bij mislukking. **/
    reason?: string
    /** Het aangemaakte object. **/
    questionConfig?: QuestionConfig
}

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

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

Deze route biedt de mogelijkheid om één QuestionConfig bij te werken.

De volgende structuur geeft alle waarden weer die gewijzigd kunnen worden:

QuestionConfig Structuur

Copy

interface QuestionConfigPatchBody {
    name?: string
    question?: string
    helpText?: string
    /** Let op! Het wijzigen van type kan de rapportage verstoren als min/max verschillend zijn. **/
    type?: QuestionConfigType
    numStars?: number
    min?: number
    max?: number
    defaultValue?: number
    labelNegative?: string
    labelPositive?: string
    subQuestionIds?: string[]
    alwaysShowSubQuestions?: boolean
    reportingOrder?: number
}

QuestionConfig Bijwerken cURL Voorbeeld

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 Bijwerken Verzoekstructuur

Copy

interface QuestionConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionConfig Bijwerken Antwoordstructuur

Copy

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

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

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

Deze route verwijdert een QuestionConfig op basis van id.

Dit verwijdert alle bijbehorende vraagresultaten (maar niet de reacties). Dit maakt deel uit van de hoge creditkosten.

Voorbeeld cURL-verzoek voor het verwijderen van QuestionConfig

Copy

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

Verzoekstructuur voor het verwijderen van QuestionConfig

Copy

interface QuestionConfigDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Antwoordstructuur voor het verwijderen van QuestionConfig

Copy

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

Structuur vraagresultaat

Om resultaten voor vragen op te slaan, maakt u een QuestionResult. U kunt vervolgens vraagresultaten aggregeren, en ook ze aan opmerkingen koppelen voor rapportagedoeleinden.

Structuur van QuestionResult

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

Deze route retourneert maximaal 1000 QuestionResults objecten tegelijk, gepagineerd. De kosten zijn 1 per 100 objecten. Ze worden gesorteerd op createdAt, oplopend. Je kunt filteren op verschillende parameters.

Voorbeeld van QuestionResults

Copy

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

Structuur van QuestionResults-verzoek

Copy

interface QuestionResultsRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** Voor paginering. Begint bij 0. **/
    skip?: number
    /** Voor paginering. **/
    limit?: number
    /** Haal de resultaten op van een specifieke pagina. **/
    urlId?: string
    /** Haal de resultaten op van een specifieke gebruiker. **/
    userId?: string
    startDate?: string | number
    questionId?: string | string[]
}

Structuur van QuestionResults-respons

Copy

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

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

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

Deze route retourneert een enkele QuestionResult met zijn id.

QuestionResult per ID cURL-voorbeeld

Copy

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

Structuur van QuestionResult-verzoek

Copy

interface QuestionResultRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van QuestionResult-respons

Copy

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

POST /api/v1/question-results

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

Dit API-eindpunt biedt de mogelijkheid om een QuestionResult aan te maken.

QuestionResult POST cURL Voorbeeld

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 Verzoekstructuur

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

QuestionResult POST Response-structuur

Copy

interface QuestionResultPostResponse {
    status: 'success' | 'failed'
    /** Opgenomen bij een mislukking. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'empty-request' | 'internal' | 'invalid-input';  
    /** Opgenomen bij een mislukking. **/
    reason?: string
    /** Het aangemaakte object. **/
    questionResult?: QuestionResult
}

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

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

Deze route biedt de mogelijkheid om één QuestionResult bij te werken.

De volgende structuur geeft alle waarden weer die gewijzigd kunnen worden:

Structuur van QuestionResult

Copy

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

cURL-voorbeeld voor QuestionResult-update

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
}'

Structuur van QuestionResult-updateverzoek

Copy

interface QuestionResultPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Structuur van QuestionResult-updateantwoord

Copy

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

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

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

Deze route zorgt voor het verwijderen van een QuestionResult op basis van id.

cURL-voorbeeld voor het verwijderen van QuestionResult

Copy

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

Verzoekstructuur voor het verwijderen van QuestionResult

Copy

interface QuestionResultDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Responsstructuur voor het verwijderen van QuestionResult

Copy

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

GET /api/v1/question-results-aggregate

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

Hier vindt de aggregatie van resultaten plaats.

De structuur van het aggregatieantwoord is als volgt:

Structuur van QuestionResultsAggregationResult

Copy

interface QuestionResultDataPoint {
    /** Een map van waarde naar het aantal keer dat die waarde voorkomt voor het huidige datapunt (datumsegment of pagina). **/
    v: Map<ValueAsString, number>
    total: number
}
interface QuestionResultsAggregationResult {
    /** Opmerking - is null wanneer timeBucket niet is opgegeven. **/
    dataByDateBucket?: Map<DateString, QuestionResultDataPoint>
    dataByUrlId?: Map<URLIdString, QuestionResultDataPoint>
    countsByValue?: Map<ValueAsString, number>
    /** Het totale aantal geaggregeerde resultaten. **/
    total: number
    /** Het resulterende gewogen gemiddelde. Het is een float, gewoonlijk twee decimalen of minder. **/
    average: number
    /** Een datumstring die aangeeft wanneer deze gegevens zijn berekend, omdat ze uit de cache kunnen komen. **/
    createdAt: string
}

Hier zijn de queryparameters die beschikbaar zijn voor aggregatie:

Structuur van het QuestionResultsAggregation-verzoek

Copy

interface QuestionResultsAggregateRequestQueryParams {
    tenantId: string
    API_KEY: string
    /** U kunt resultaten aggregeren voor één of meer vragen. **/
    questionId: string | string[]
    startDate?: string | number
    timeBucket?: 'day' | 'month' | 'year'
    /** Aggregeren voor een specifieke pagina. **/
    urlId?: string
    /** Aggregeren voor een specifieke gebruiker. **/
    userId?: string
    /** Forceer direct opnieuw berekenen en werk de cache bij. **/
    forceRecalculate?: boolean
}

Hier is een voorbeeldverzoek:

Voorbeeld van QuestionResultsAggregation

Copy

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

Voorbeeldantwoord:

Voorbeeldantwoord van QuestionResultsAggregation

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
    }

Structuur van het QuestionResultsAggregation-antwoord

Copy

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

Prestatieopmerkingen

Bij een cache-miss duren aggregaties doorgaans vijf seconden per miljoen resultaten.
In andere gevallen zijn verzoeken constant qua tijd.

Cache- en kostenopmerkingen

Wanneer forceRecalculate is opgegeven, zijn de kosten altijd 10, in plaats van de normale 2.
Als de cache verloopt en de gegevens opnieuw worden berekend, blijven de kosten een constante 2 als forceRecalculate niet is opgegeven. De cache verloopt afhankelijk van de grootte van de geaggregeerde dataset (kan variëren tussen 30 seconden en 5 minuten).
Dit is om het gebruik van de cache te stimuleren.

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

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

Dit is waar de combinatie van resultaten met reacties plaatsvindt. Handig voor het maken van een grafiek met "recente positieve en negatieve reacties" voor een product, bijvoorbeeld.

Je kunt zoeken via een bereik van waarden (inclusief), één of meer vragen, en op een begindatum (inclusief).

De response-structuur is als volgt:

Structuur van QuestionResultsCombinedWithCommentsResponse

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 {
    /** Een datumtekenreeks die aangeeft wanneer deze gegevens zijn berekend, aangezien ze uit de cache kunnen komen. **/
    createdAt: string
    results: CommentAndResult[]
}

Hier zijn de queryparameters die beschikbaar zijn voor aggregatie:

Structuur van QuestionResultsCombineComments Request

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
}

Hier is een voorbeeldverzoek:

Voorbeeld van QuestionResultsCombineComments

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'

Voorbeeldresponse:

Voorbeeldantwoord van QuestionResultsCombineComments

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
            }
        }
    ]
}

Structuur van de response van QuestionResultsCombineComments

Copy

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

Caching- en kostenopmerkingen

Wanneer forceRecalculate is opgegeven, zijn de kosten altijd 10, in plaats van de normale 2.
Als de cache verloopt en de gegevens opnieuw worden berekend, blijven de kosten constant 2 wanneer forceRecalculate niet is opgegeven.
Dit is bedoeld om het gebruik van de cache te stimuleren.

Structuur gebruikersbadge

UserBadge is een object dat een badge voorstelt die aan een gebruiker is toegewezen in het FastComments-systeem.

Badges kunnen automatisch aan gebruikers worden toegekend op basis van hun activiteit (zoals aantal reacties, reactietijd, veteranenstatus) of handmatig door sitebeheerders.

De structuur van het UserBadge-object is als volgt:

Structuur van UserBadge

Copy

export interface UserBadge {
    /** Unieke identificatie voor deze gebruikersbadge-toewijzing */
    id: string
    /** ID van de gebruiker waaraan deze badge is toegewezen */
    userId: string
    /** ID van de badge-definitie uit de catalogus van de tenant */
    badgeId: string
    /** ID van de tenant die deze badge heeft gemaakt/toegewezen */
    fromTenantId: string
    /** Wanneer deze badge is gemaakt (milliseconden sinds epoch) */
    createdAt?: number
    /** Wanneer deze badge door de gebruiker is ontvangen (milliseconden sinds epoch) */
    receivedAt?: number
    /** 
     * Het badgetype: 
     * 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
    /** Voor drempelgebaseerde badges, de drempelwaarde */
    threshold?: number
    /** De naam/label van de badge */
    name?: string
    /** Gedetailleerde beschrijving van de badge */
    description?: string
    /** De tekst die op de badge wordt weergegeven */
    displayLabel?: string
    /** URL naar een afbeelding die op de badge wordt weergegeven */
    displaySrc?: string
    /** Achtergrondkleur voor de badge (hex-code) */
    backgroundColor?: string
    /** Randkleur voor de badge (hex-code) */
    borderColor?: string
    /** Tekstkleur voor de badge (hex-code) */
    textColor?: string
    /** Aanvullende CSS-klasse voor opmaak */
    cssClass?: string
    /** Voor veteranenbadges, de tijdsdrempel in milliseconden */
    veteranUserThresholdMillis?: number
    /** Of deze badge wordt weergegeven bij de reacties van de gebruiker */
    displayedOnComments: boolean
    /** De weergavevolgorde van de badge */
    order?: number
}

---

GET /api/v1/user-badges

Deze endpoint stelt je in staat gebruikersbadges op te halen op basis van verschillende criteria.

Voorbeeldverzoek:

Voorbeeld GET-verzoek

Copy

Run

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

Je kunt verschillende queryparameters toevoegen om de resultaten te filteren:

userId - Haal badges op voor een specifieke gebruiker
badgeId - Haal instanties van een specifieke badge op
type - Filter op badgetype (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies, etc. Zie de UserBadge-structuur voor de volledige lijst)
displayedOnComments - Filter op of de badge wordt getoond bij reacties (true/false)
limit - Maximaal aantal badges om terug te geven (standaard 30, max 200)
skip - Aantal badges om over te slaan (voor paginering)

Voorbeeldantwoord:

Respons

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
    }
  ]
}

Mogelijke foutreacties:

Fout: Ontbrekend Tenant ID

Copy

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

Fout: Ongeldige limiet

Copy

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

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

Dit eindpunt stelt u in staat een specifieke gebruikersbadge op te halen op basis van het unieke ID.

Voorbeeldverzoek:

Voorbeeld van een GET-aanvraag

Copy

Run

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

Voorbeeldrespons:

Respons

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
  }
}

Mogelijke foutmeldingen:

Fout: Ontbrekende Tenant-ID

Copy

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

Fout: Niet gevonden

Copy

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

POST /api/v1/user-badges

Deze endpoint stelt u in staat een nieuwe toewijzing van een gebruikersbadge aan te maken.

Voorbeeldverzoek:

POST-aanvraagvoorbeeld

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
}'

De request-body moet de volgende parameters bevatten:

userId (verplicht) - De ID van de gebruiker aan wie de badge moet worden toegewezen
badgeId (verplicht) - De ID van de te toewijzen badge
displayedOnComments (optioneel) - Of de badge moet worden weergegeven bij de opmerkingen van de gebruiker (standaard: true)

Belangrijke opmerkingen:

De badge moet bestaan en ingeschakeld zijn in de badgecatalogus van uw tenant
U kunt alleen badges toewijzen aan gebruikers die tot uw tenant behoren of op uw site hebben gereageerd

Voorbeeldrespons:

Respons

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
  }
}

Mogelijke foutmeldingen:

Fout: Ontbrekende Tenant-ID

Copy

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

Fout: Ontbrekend gebruikers-ID

Copy

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

Fout: Ontbrekend Badge-ID

Copy

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

Fout: Badge niet gevonden

Copy

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

Fout: Ongeautoriseerde gebruiker

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

Deze endpoint stelt u in staat om een toewijzing van een gebruikersbadge bij te werken.

Momenteel is de enige eigenschap die kan worden bijgewerkt displayedOnComments, die bepaalt of de badge wordt weergegeven bij de reacties van de gebruiker.

Voorbeeldverzoek:

Voorbeeld PUT-verzoek

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
}'

Voorbeeldantwoord:

Antwoord

Copy

{
  "status": "success"
}

Mogelijke foutreacties:

Fout: Ontbrekende Tenant-ID

Copy

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

Fout: Ontbrekend ID

Copy

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

Fout: Niet gevonden

Copy

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

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

Deze endpoint stelt je in staat een toewijzing van een gebruikersbadge te verwijderen.

Voorbeeldverzoek:

Voorbeeld DELETE-aanvraag

Copy

Run

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

Voorbeeldantwoord:

Antwoord

Copy

{
  "status": "success"
}

Mogelijke foutantwoorden:

Fout: Ontbrekend Tenant-ID

Copy

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

Fout: Ontbrekend ID

Copy

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

Fout: Niet gevonden

Copy

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

Structuur voortgang gebruikersbadge

UserBadgeProgress is een object dat de voortgang van een gebruiker bijhoudt naar het verdienen van verschillende badges in het FastComments-systeem.

Deze bijhouding helpt bepalen wanneer gebruikers automatisch badges moeten ontvangen op basis van hun activiteit en deelname in uw community.

De structuur van het UserBadgeProgress-object is als volgt:

Structuur van UserBadgeProgress

Copy

export interface UserBadgeProgress {
    /** Unieke identificatie voor dit voortgangsrecord */
    id: string
    /** ID van de tenant waartoe dit voortgangsrecord behoort */
    tenantId: string
    /** ID van de gebruiker die door dit voortgangsrecord wordt gevolgd */
    userId: string
    /** ID van de eerste reactie van de gebruiker in het systeem */
    firstCommentId?: string
    /** Datum van de eerste reactie van de gebruiker (milliseconden sinds epoch) */
    firstCommentDate?: number
    /** Automatisch berekende vertrouwensfactor op basis van gebruikersactiviteit */
    autoTrustFactor?: number
    /** Handmatig ingestelde vertrouwensfactor door beheerders */
    manualTrustFactor?: number
    /** Gedetailleerd voortgangsobject met verschillende statistieken, keys komen overeen met de BadgeType-enum */
    progress: {
        /** 0: CommentCount - Aantal reacties dat de gebruiker heeft geplaatst */
        '0'?: number
        /** 1: CommentUpVotes - Aantal upvotes die de gebruiker heeft ontvangen */
        '1'?: number
        /** 2: CommentReplies - Aantal reacties (replies) die de gebruiker heeft geplaatst */
        '2'?: number
        /** 3: CommentsPinned - Aantal vastgezette reacties die de gebruiker heeft */
        '3'?: number
        /** 4: Veteran - Accountleeftijd van de gebruiker */
        '4'?: number
        /** 5: NightOwl - Aantal keer dat de gebruiker heeft gepost tijdens nachtelijke uren */
        '5'?: number
        /** 6: FastReplyTime - Gemiddelde reactietijd in milliseconden */
        '6'?: number
        /** 7: ModeratorCommentsDeleted - Voor moderatorbadges, aantal verwijderde reacties */
        '7'?: number
        /** 8: ModeratorCommentsApproved - Voor moderatorbadges, aantal goedgekeurde reacties */
        '8'?: number
        /** 9: ModeratorCommentsUnapproved - Voor moderatorbadges, aantal niet-goedgekeurde reacties */
        '9'?: number
        /** 10: ModeratorCommentsReviewed - Voor moderatorbadges, aantal beoordeelde reacties */
        '10'?: number
        /** 11: ModeratorCommentsMarkedSpam - Voor moderatorbadges, aantal reacties gemarkeerd als spam */
        '11'?: number
        /** 12: ModeratorCommentsMarkedNotSpam - Voor moderatorbadges, aantal reacties gemarkeerd als geen spam */
        '12'?: number
        /** 13: RepliedToSpecificPage - Voor elke pagina, aantal antwoorden */
        '13'?: Record<string, number>
    }
}

---

GET /api/v1/user-badge-progress

Met deze endpoint kunt u voortgangsgegevens van gebruikersbadges ophalen op basis van verschillende criteria.

Voorbeeldverzoek:

Voorbeeld GET-aanvraag

Copy

Run

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

U kunt verschillende queryparameters toevoegen om de resultaten te filteren:

userId - Haal voortgang op voor een specifieke gebruiker
limit - Maximum aantal records om te retourneren (standaard 30, max 200)
skip - Aantal records om over te slaan (voor paginering)

Voorbeeldantwoord:

Antwoord

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
      }
    }
  ]
}

Mogelijke foutreacties:

Fout: Ontbrekende Tenant ID

Copy

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

Fout: Ongeldige waarde voor limit

Copy

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

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

Dit eindpunt stelt u in staat om een specifiek voortgangsrecord van een gebruikersbadge op te halen met behulp van het unieke ID.

Voorbeeldaanvraag:

Voorbeeld van een GET-aanvraag

Copy

Run

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

Voorbeeldrespons:

Antwoord

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
    }
  }
}

Mogelijke foutreacties:

Fout: Ontbrekend Tenant ID

Copy

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

Fout: Niet gevonden

Copy

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

---

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

Dit eindpunt stelt je in staat het badge-voortgangsrecord van een gebruiker op te halen op basis van hun user ID.

Voorbeeldverzoek:

GET-aanvraagvoorbeeld

Copy

Run

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

Voorbeeldrespons:

Respons

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
    }
  }
}

Mogelijke foutreacties:

Fout: Ontbrekende Tenant ID

Copy

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

Fout: Ontbrekende User ID

Copy

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

Fout: Niet gevonden

Copy

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

---

Tot slot

We hopen dat je onze API-documentatie grondig en gemakkelijk te begrijpen hebt gevonden. Als je hiaten vindt, laat het ons hieronder weten.

Taal 🇳🇱 Nederlands

API-bronnen

Aggregaties

Auditlogs

Reacties

E-mailsjablonen

Hashtags

Moderators

Aantal meldingen

Meldingen

Pagina's

Wachtende webhook-gebeurtenissen

SSO-gebruikers

Abonnementen

Dagelijks gebruik per tenant

Tenants

Tenantpakketten

Tenantgebruikers

Gebruikers

Stemmen

Domeinconfiguraties

Vraagconfiguraties

Vraagresultaten

Vraagresultatenaggregatie

Gebruikersbadges

Voortgang gebruikersbadge

De FastComments API

Gegenereerde SDK's

Authenticatie

Beveiligingsnotitie

Authenticatieoptie één - Headers

Authenticatieoptie twee - Query-parameters

API-bronnen

Gebruik van resources

Opmerking!

Aggregeer uw gegevens

Voorbeelden

Voorbeeld: Unieke waarden tellen

Voorbeeld: Aantal unieke waarden

Voorbeeld: Som van waarden van meerdere velden

Voorbeeld: Gemiddelde waarden van meerdere velden

Voorbeeld: Min/Max waarden van meerdere velden

Voorbeeld: Unieke waarden tellen voor meerdere velden

Voorbeeld: Query aanmaken

Voorbeeld: Aantal opmerkingen in afwachting van beoordeling

Voorbeeld: Opsplitsing van goedgekeurde, beoordeelde en spam-opmerkingen

Structuren

Auditlogstructuur

GET /api/v1/audit-logs

Reactiestructuur

Structuur van de opmerkingstekst

Tagging

HashTags

GET /api/v1/comments

Paginering

Threads

Bomen uitgelegd

Reacties ophalen in de context van een gebruiker

Reacties als boom ophalen

Reacties als boom ophalen, zoeken op hashtag

Alle verzoekparameters

De respons

Handige tips

URL ID

Anonieme acties

Reacties worden niet geretourneerd

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-mailsjabloonstructuur

Opmerkingen

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

GET /api/v1/email-templates

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

POST /api/v1/email-templates