API | FastComments Docs

The FastComments API

FastComments предоставя API за взаимодействие с множество ресурси. Създавайте интеграции с нашата платформа или дори изграждайте свои собствени клиенти!

В тази документация ще намерите всички поддържани ресурси от API, документирани с техните типове заявки и отговори.

За корпоративни клиенти, целият достъп до API се записва в дневника на одита.

Generated SDKs

FastComments вече генерира един API Spec от нашия код (това все още не е пълно, но включва много APIs).

Също така вече разполагаме със SDK за популярни езици:

Authentication

API-то се удостоверява чрез подаване на вашия api key като или X-API-KEY хедър, или като API_KEY query параметър. Също така ще ви е необходим вашият tenantId за извършване на API повиквания. Той може да бъде получен от същата страница като вашия api key.

Security Note

Тези рутове са предназначени да се вика от сървър. НЕ ги викайте от браузър. Правенето на това ще изложи вашия API key - това ще предостави пълен достъп до вашия акаунт на всеки, който може да види изходния код на страница!

Authentication Option One - Headers

Хедър: X-API-KEY
Хедър: X-TENANT-ID

Authentication Option Two - Query Parameters

Параметър на заявката: API_KEY
Параметър на заявката: tenantId

Ресурси на API

Използване на ресурси

Трябва да се отбележи, че извличането на данни от API се брои като използване на вашия акаунт.

Всеки ресурс ще посочи какво е това използване в собствения си раздел.

Някои ресурси струват повече за обслужване от други. Всяка крайна точка има определена цена от кредити за API извикване. За някои крайни точки броят на кредитите варира в зависимост от опциите и размера на отговорите.

Използването на API може да се провери на страницата Анализ на фактуриране и се актуализира на всеки няколко минути.

Забележка!

Препоръчваме първо да прочетете документацията за Pages, за да ограничите объркването при определяне какви стойности да подадете за urlId в Comment API.

Обобщете данните си

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

Този API агрегира документи, като ги групира (ако е предоставен groupBy) и прилага множество операции. Поддържат се различни операции (напр. sum, countDistinct, avg и др.).

Цената е променлива. Всеки 500 сканирани обекта струва 1 API кредит.

Максималното използване на паметта, разрешено за API извикване по подразбиране, е 64MB и по подразбиране можете да имате само една агрегация, работеща едновременно. Ако изпратите множество агрегации едновременно, те ще бъдат поставени на опашка и ще се изпълняват в реда на подаване. Чакащите агрегации ще изчакат максимум 60 секунди, след което заявката ще изтече. Отделните агрегации могат да работят до 5 минути.

Ако имате управлявани наематели, можете да агрегирате всички ресурси на дъщерните наематели в едно извикване, като подадете параметъра parentTenantId в заявката.

Примери

Пример: Брой уникални

Пример за броене на уникални стойности с cURL

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

Отговор за брой уникални стойности

Copy

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

Пример: Брой различни

Пример за броене на различни стойности с cURL

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

Отговор:

Отговор за брой различни стойности

Copy

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

Пример: Сума на стойности от множество полета

Пример за сума на стойности с cURL

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

Отговор:

Отговор за сума на стойности

Copy

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

Пример: Средна стойност на множество полета

Пример за средна стойност с cURL

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

Отговор:

Отговор за средна стойност

Copy

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

Пример: Минимални/Максимални стойности на множество полета

Пример за минимални/максимални стойности с cURL

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

Отговор:

Отговор за минимални/максимални стойности

Copy

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

Пример: Брой уникални стойности на множество полета

Пример за броене на уникални стойности с cURL

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

Отговор:

Отговор за броене на уникални стойности

Copy

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

Пример: Създаване на заявка

Пример за създаване на заявка с cURL

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

Отговор:

Отговор за създаване на заявка

Copy

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

Пример: Брой коментари, чакащи преглед

Пример за броене на коментари, чакащи преглед с cURL

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

Отговор:

Отговор за броене на коментари, чакащи преглед

Copy

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

Пример: Разбивка на одобрени, прегледани и спам коментари

Пример за разбивка на коментари с cURL

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

Отговор:

Отговор за разбивка на коментари

Copy

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

Структури

Структура на заявка за агрегация

Copy

export type AggregationOpType = 'sum' | 'countDistinct' | 'distinct' | 'avg' | 'min' | 'max' | 'count';
/** An operation that will be applied on a field */
export interface AggregationOperation {
    /** The field to operate on */
    field: string;
    /** The type of operation */
    op: AggregationOpType;
    /** Optional alias for the output; if not provided, a default alias is computed */
    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
};

Структура на отговор за агрегация

Copy

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

Следните ресурси могат да бъдат агрегирани:

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

Структура на AuditLog

AuditLog е обект, който представлява одитирано събитие за наематели, които имат достъп до тази функция.

Структурата на обекта AuditLog е следната:

Структура на AuditLog

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

Одитният дневник е неизменяем. Също така не може да се записва ръчно. Само FastComments.com може да реши кога да записва в одитния дневник. Въпреки това можете да четете от него чрез този API.

Събитията в одитния дневник изтичат след две години.

GET /api/v1/audit-logs

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

Този API използва странициране, предоставено от параметрите skip, before и after. AuditLogs се връщат на страници от 1000, подредени по when и id.

Извличането на всеки 1000 лога има кредитна цена от 10.

По подразбиране ще получите списък с най-новите елементи първи. По този начин можете да анкетирате, започвайки от skip=0, страници докато намерите последния запис, който сте консумирали.

Алтернативно, можете да сортирате най-старите първи и да страницирате докато няма повече записи.

Сортирането може да се направи като зададете order на ASC или DESC. По подразбиране е ASC.

Заявка по дата е възможна чрез before и after като времеви печати с милисекунди. before и after НЕ са включителни.

Пример за AuditLog с cURL

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

Copy

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

Структура на отговора за AuditLog

Copy

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

Структура на коментара

Обектът Comment представлява коментар, оставен от потребител.

Връзката между родителски и дъщерни коментари се определя чрез parentId.

Структурата на обекта Comment е следната:

Структура на Comment

Copy

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

Някои от тези полета са маркирани като READONLY - те се връщат от API, но не могат да бъдат зададени.

Структура на текста на коментара

Коментарите се пишат във FastComments вариант на markdown, който е просто markdown плюс традиционни bbcode стилови тагове за изображения, като [img]path[/img].

Текстът се съхранява в две полета. Текстът, въведен от потребителя, се съхранява непроменен в полето comment. Той се обработва и съхранява в полето commentHTML.

Позволените HTML тагове са b, u, i, strike, pre, span, code, img, a, strong, ul, ol, li, и br.

Препоръчително е да визуализирате HTML, тъй като е много малко подмножество от HTML, изграждането на визуализатор е доста лесно. Има множество библиотеки за React Native и Flutter, например, които да помогнат с това.

Можете да изберете да визуализирате ненормализираната стойност на полето comment. Примерен парсер е тук..

Примерният парсер може също да бъде адаптиран да работи с HTML и да трансформира HTML таговете в очакваните елементи за визуализация за вашата платформа.

Отбелязване

Когато потребителите са отбелязани в коментар, информацията се съхранява в списък, наречен mentions. Всеки обект в този списък има следната структура.

Обектът Comment Mentions

Copy

Run

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

Хаштагове

Когато се използват хаштагове и са успешно обработени, информацията се съхранява в списък, наречен hashTags. Всеки обект в този списък има следната структура. Хаштаговете могат също да бъдат ръчно добавени към масива hashTags на коментара за заявки, ако retain е зададен.

Обектът Comment HashTag

Copy

Run

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

GET /api/v1/comments

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

Този API се използва за получаване на коментари за показване на потребител. Например, автоматично филтрира неодобрени или спам коментари.

Странициране

Страницирането може да се направи по един от два начина, в зависимост от изискванията за производителност и случая на употреба:

Най-бързо: Предварително изчислено странициране:
1. Така работи FastComments, когато използвате нашите готови уиджети и клиенти.
2. Щракването върху "следващ" просто увеличава броя на страниците.
3. Можете да мислите за това като извличане чрез хранилище ключ-стойност.
4. По този начин просто дефинирайте параметър page, започващ от 0, и посока на сортиране като direction.
5. Размерите на страниците могат да бъдат персонализирани чрез правила за персонализация.
Най-гъвкаво: Гъвкаво странициране:
1. По този начин можете да дефинирате персонализирани параметри limit и skip. Не подавайте page.
2. Посока на сортиране direction също се поддържа.
3. limit е общият брой за връщане след прилагане на skip.
  - Пример: задайте skip = 200, limit = 100, когато page size = 100 и page = 2.
4. Дъщерните коментари все още се броят при страницирането. Можете да заобиколите това, като използвате опцията asTree.
  - Можете да странирате децата чрез limitChildren и skipChildren.
  - Можете да ограничите дълбочината на върнатите нишки чрез maxTreeDepth.

Нишки

Когато използвате Предварително изчислено странициране, коментарите се групират по страница и коментарите в нишки влияят на общата страница.
1. По този начин нишките могат да се определят на клиента въз основа на parentId.
2. Например, със страница с един коментар от най-високо ниво и 29 отговора, и задаване на page=0 в API - ще получите само коментара от най-високо ниво и 29-те деца.
3. Примерно изображение тук, илюстриращо множество страници.
Когато използвате Гъвкаво странициране, можете да дефинирате параметър parentId.
1. Задайте това на null, за да получите само коментари от най-високо ниво.
2. След това, за да видите нишки, извикайте API отново и подайте parentId.
3. Често срещано решение е да направите API извикване за коментарите от най-високо ниво и след това да направите паралелни API извиквания, за да получите коментарите за децата на всеки коментар.
НОВО от февруари 2023! Извличане като дърво с използване на &asTree=true.
1. Можете да мислите за това като Гъвкаво странициране като дърво.
2. Само коментарите от най-високо ниво се броят при страницирането.
3. Задайте parentId=null, за да започнете дървото от корена (трябва да зададете parentId).
4. Задайте skip и limit за странициране.
5. Задайте asTree на true.
6. Цената на кредитите се увеличава с 2x, тъй като нашият бекенд трябва да свърши много повече работа в този сценарий.
7. Задайте maxTreeDepth, limitChildren и skipChildren по желание.

Обяснение на дърветата

Когато използвате asTree, може да е трудно да разсъждавате за страницирането. Ето полезна графика:

Диаграма на странициране на дърво

Извличане на коментари в контекста на потребител

API /comments може да се използва в два контекста, за различни случаи на употреба:

За връщане на коментари, сортирани и маркирани с информация за изграждане на ваш собствен клиент.
- В този случай дефинирайте параметър на заявката contextUserId.
За извличане на коментари от вашия бекенд за персонализирани интеграции.
- Платформата ще използва това по подразбиране без contextUserId.

Предварително изчислено странициране на коментари

Copy

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

Гъвкаво странициране на коментари

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'

Гъвкаво странициране на коментари в контекст на потребител

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'

Гъвкаво странициране на коментари в контекст на потребител само за коментари от най-високо ниво

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'

Получаване на коментари като дърво

Възможно е коментарите да се върнат като дърво, като страницирането брои само коментарите от най-високо ниво.

Коментари като дърво в контекст на потребител

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'

Искате да получите само коментарите от най-високо ниво и непосредствените деца? Ето един начин:

Коментари като дърво с максимална дълбочина

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'

Въпреки това, във вашия потребителски интерфейс може да се наложи да знаете дали да покажете бутон "покажи отговорите" на всеки коментар. Когато извличате коментари чрез дърво, има свойство hasChildren, маркирано към коментарите, когато е приложимо.

Получаване на коментари като дърво, търсене по хаштаг

Възможно е да търсите по хаштаг с помощта на API, в целия ви tenant (не е ограничено до една страница или urlId).

В този пример пропускаме urlId и търсим по множество хаштагове. API ще върне само коментари, които имат всички заявени хаштагове.

Коментари като дърво в контекст на потребител, по хаштаг

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'

Всички параметри на заявката

Структура на заявката за коментари

Copy

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

Отговорът

Структура на отговора за коментари

Copy

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

Полезни съвети

URL ID

Вероятно искате да използвате API Comment с параметъра urlId. Можете първо да извикате API Pages, за да видите как изглеждат наличните за вас стойности на urlId.

Анонимни действия

За анонимно коментиране вероятно искате да подадете anonUserId, когато извличате коментари и когато извършвате докладване и блокиране.

(!) Това е необходимо за много магазини за приложения, тъй като потребителите трябва да могат да докладват съдържание, създадено от потребители, което могат да видят, дори ако не са влезли. Неизпълнението на това може да доведе до премахване на приложението ви от съответния магазин.

Коментарите не се връщат

Проверете дали вашите коментари са одобрени и не са спам.

GET /api/v1/comments/:id

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

Този API предоставя възможност за извличане на единичен коментар по id.

Пример за получаване на коментар по Id с cURL

Copy

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

Структура на заявката за получаване на коментар по Id

Copy

interface CommentsGetByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за получаване на коментар по Id

Copy

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

POST /api/v1/comments

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

Тази API крайна точка предоставя възможност за създаване на коментари.

Често срещани случаи на употреба са персонализирани потребителски интерфейси, интеграции или импортиране.

Забележки:

Този API може да актуализира уиджета за коментари "на живо" ако желаете (това увеличава creditsCost от 1 на 2).
Този API автоматично ще създаде потребителски обекти в нашата система, ако е предоставен имейл.
Опитът да запазите два коментара с различни имейли, но с едно и също потребителско име, ще доведе до грешка за втория коментар.
Ако посочвате parentId и дъщерният коментар има notificationSentForParent като false, ние ще изпратим известия за родителския коментар. Това се прави на всеки час (групираме известията заедно, за да намалим броя на изпратените имейли).
Ако искате да изпращате приветствени имейли при създаване на потребители или имейли за потвърждение на коментари, задайте sendEmails на true в параметрите на заявката.
Коментарите, създадени чрез този API, ще се показват в страниците за анализ и модерация на административното приложение.
"лошите думи" все още се маскират в имената на коментиращите и текста на коментарите, ако настройката е включена.
Коментарите, създадени чрез този API, все още могат да бъдат проверявани за спам, ако желаете.
Конфигурацията като максимална дължина на коментара, ако е конфигурирана чрез административната страница за правила за персонализация, ще се прилага тук.

Минималните данни, необходими за изпращане, които ще се показват в уиджета за коментари, са следните:

Пример за минимален POST на коментар с cURL

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

По-реалистична заявка може да изглежда така:

Пример за POST на коментар с cURL

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

Структура на заявката за POST на коментар

Copy

interface CommentPostQueryParams {
    tenantId: string
    API_KEY: string
    doSpamCheck?: 'true' | 'false'
    /** Whether the comment should appear "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
    sendEmails?: 'true' | 'false'
    populateNotifications?: 'true' | 'false'
}

Структура на отговора за POST на коментар

Copy

interface CommentPostResponse {
    status: 'success' | 'failed'
    /** Included on failure. **/
    code?: 'missing-tenant-id' | 'invalid-tenant-id' | 'invalid-api-key' | 'missing-api-key' | 'missing-url-id' | 'empty-comment' | 'comment-too-big' | 'hash-tags-readonly' | 'mentions-readonly' | 'invalid-user' | 'unauthorized' | 'invalid-date' | 'invalid-name' | 'invalid-name-is-email' | 'banned' | 'invalid-email';
    /** Included on failure. **/
    reason?: string
    /** The created comment. **/
    comment?: Comment
    /** The associated user, which may or may not have already existed. **/
    user?: User
}

PATCH /api/v1/comments/:id

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

Тази API крайна точка предоставя възможност за актуализиране на единичен коментар.

Забележки:

Този API може да актуализира уиджета за коментари "на живо" ако желаете (това увеличава базовата creditsCost от 1 на 2).
- Това може да направи мигрирането на коментари между страници "на живо" (промяна на urlId).
- Миграциите струват допълнително 2 кредита, тъй като страниците се предварително изчисляват и това е CPU интензивно.
За разлика от API за създаване, този API НЯМА автоматично да създава потребителски обекти в нашата система, ако е предоставен имейл.
Коментарите, актуализирани чрез този API, все още могат да бъдат проверявани за спам, ако желаете.
Конфигурацията като максимална дължина на коментара, ако е конфигурирана чрез административната страница за правила за персонализация, ще се прилага тук.
За да позволите на потребителите да актуализират текста на коментара си, можете просто да посочите comment в тялото на заявката. Ние ще генерираме резултатния commentHTML.
- Ако дефинирате и comment, и commentHTML, ние няма автоматично да генерираме HTML.
- Ако потребителят добави споменавания или хаштагове в новия си текст, той все още ще бъде обработен като POST API.
Когато актуализирате commenterEmail на коментар, е най-добре също да посочите userId. В противен случай трябва да се уверите, че потребителят с този имейл принадлежи на вашия tenant, или заявката ще се провали.

Пример за минимален PATCH на коментар с cURL

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

Структура на заявката за PATCH на коментар

Copy

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

Структура на отговора за PATCH на коментар

Copy

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

DELETE /api/v1/comments/:id

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

Тази API крайна точка предоставя възможност за изтриване на коментар.

Забележки:

Този API може да актуализира уиджета за коментари "на живо" ако желаете (това увеличава creditsCost от 1 на 2).
Този API ще изтрие всички дъщерни коментари.

Пример за DELETE на коментар с cURL

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'

Структура на заявката за DELETE на коментар

Copy

interface CommentDeleteQueryParams {
    tenantId: string
    API_KEY: string
    /** The user doing the update. If desired can be used to check that they can delete the comment.  **/
    contextUserId?: string
    /** Whether the comment should be deleted "live" to users viewing instances of the comment widget with the same urlId. NOTE: Doubles credit cost from 1 to 2. **/
    isLive?: 'true' | 'false'
}

Структура на отговора за DELETE на коментар

Copy

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

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

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

Тази API крайна точка предоставя възможност за докладване на коментар за конкретен потребител.

Забележки:

Това извикване винаги трябва да се прави в контекста на потребител. Потребителят може да бъде FastComments.com потребител, SSO потребител или Tenant потребител.
Ако е зададен праг за докладване-скриване, коментарът ще бъде автоматично скрит на живо след като бъде докладван определен брой пъти.
След като бъде автоматично неодобрен (скрит) - коментарът може да бъде повторно одобрен само от администратор или модератор. Премахването на докладването няма да одобри отново коментара.

Пример за докладване на коментар с cURL

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'

За анонимно докладване трябва да посочим anonUserId. Това може да бъде ID, който представлява анонимната сесия, или случаен UUID. Това ни позволява да поддържаме докладване и премахване на докладване на коментари дори ако потребителят не е влязъл в системата. По този начин коментарът може да бъде маркиран като докладван, когато коментарите се извличат със същия anonUserId.

Пример за анонимно докладване на коментар с cURL

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'

Структура на заявката за докладване на коментар

Copy

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

Структура на отговора за докладване на коментар

Copy

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

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

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

Тази API крайна точка предоставя възможност за премахване на докладването на коментар за конкретен потребител.

Забележки:

Това извикване винаги трябва да се прави в контекста на потребител. Потребителят може да бъде FastComments.com потребител, SSO потребител или Tenant потребител.
След като коментарът е автоматично неодобрен (скрит) - коментарът може да бъде повторно одобрен само от администратор или модератор. Премахването на докладването няма да одобри отново коментара.

Пример за премахване на докладване на коментар с cURL

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'

За анонимно докладване трябва да посочим anonUserId. Това може да бъде ID, който представлява анонимната сесия, или случаен UUID.

Пример за анонимно премахване на докладване на коментар с cURL

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'

Структура на заявката за премахване на докладване на коментар

Copy

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

Структура на отговора за премахване на докладване на коментар

Copy

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

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

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

Тази API крайна точка предоставя възможност за блокиране на потребител, написал даден коментар. Поддържа блокиране от коментари, написани от FastComments.com потребители, SSO потребители и Tenant потребители.

Поддържа параметър commentIdsToCheck в тялото, за да провери дали други потенциално видими коментари на клиента трябва да бъдат блокирани/отблокирани след извършване на това действие.

Забележки:

Това извикване винаги трябва да се прави в контекста на потребител. Потребителят може да бъде FastComments.com потребител, SSO потребител или Tenant потребител.
userId в заявката е потребителят, който извършва блокирането. Например: Потребител A иска да блокира Потребител B. Подайте userId=Потребител A и id на коментара, който Потребител B е написал.
Напълно анонимни коментари (без потребителски id, без имейл) не могат да бъдат блокирани и ще бъде върната грешка.

Пример за блокиране на коментар с cURL

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'

За анонимно блокиране трябва да посочим anonUserId. Това може да бъде ID, който представлява анонимната сесия, или случаен UUID. Това ни позволява да поддържаме блокиране на коментари дори ако потребителят не е влязъл в системата, като извличаме коментарите със същия anonUserId.

Пример за анонимно блокиране на коментар с cURL

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'

Структура на заявката за блокиране на коментар

Copy

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

Структура на отговора за блокиране на коментар

Copy

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

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

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

Тази API крайна точка предоставя възможност за отблокиране на потребител, написал даден коментар. Поддържа отблокиране от коментари, написани от FastComments.com потребители, SSO потребители и Tenant потребители.

Забележки:

Това извикване винаги трябва да се прави в контекста на потребител. Потребителят може да бъде FastComments.com потребител, SSO потребител или Tenant потребител.
userId в заявката е потребителят, който извършва отблокирането. Например: Потребител A иска да отблокира Потребител B. Подайте userId=Потребител A и id на коментара, който Потребител B е написал.
Напълно анонимни коментари (без потребителски id, без имейл) не могат да бъдат блокирани и ще бъде върната грешка.

Пример за отблокиране на коментар с cURL

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

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'

Структура на заявката за отблокиране на коментар

Copy

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

Структура на отговора за отблокиране на коментар

Copy

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

Структура на шаблон за имейл

Обектът EmailTemplate представлява конфигурация за персонализиран имейл шаблон за tenant.

Системата ще избере имейл шаблона за използване чрез:

Неговия идентификатор на типа, наречен emailTemplateId. Това са константи.
domain. Първо ще се опитаме да намерим шаблон за домейна, към който е свързан съответният обект (като Comment), и ако не бъде намерено съвпадение, ще се опитаме да намерим шаблон, където domain е null или *.

Структурата на обекта EmailTemplate е следната:

Структура на Email Template

Copy

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

Забележки

Можете да получите валидните стойности на emailTemplateId от крайната точка /definitions.
Крайната точка /definitions също включва преводите по подразбиране и тестовите данни.
Шаблоните няма да се запазят с невалидна структура или тестови данни.

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

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

Индивидуални EmailTemplates могат да бъдат извлечени по съответния им id (НЕ emailTemplateId).

Пример за EmailTemplate по ID с cURL

Copy

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

Структура на заявката за EmailTemplate по ID

Copy

interface EmailTemplatesByIdRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за EmailTemplate по ID

Copy

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

GET /api/v1/email-templates

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

Този API използва странициране, предоставено от параметъра на заявката page. EmailTemplates се връщат на страници от 100, подредени по createdAt и след това id.

Пример за EmailTemplate с cURL

Copy

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

Структура на заявката за EmailTemplate

Copy

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

Структура на отговора за EmailTemplate

Copy

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

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

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

Тази API крайна точка предоставя възможност за актуализиране на имейл шаблон, като посочите само id и атрибутите за актуализиране.

Имайте предвид, че всички същите валидации за създаване на шаблон се прилагат, например:

Шаблонът трябва да се визуализира. Това се проверява при всяка актуализация.
Не можете да имате дублирани шаблони за същия домейн (в противен случай един ще бъде мълчаливо игнориран).

Пример за PATCH на EmailTemplate с cURL

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

Структура на заявката за PATCH на EmailTemplate

Copy

interface EmailTemplatePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за PATCH на EmailTemplate

Copy

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

POST /api/v1/email-templates

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

Тази API крайна точка предоставя възможност за създаване на имейл шаблони.

Забележки:

Не можете да имате множество шаблони с един и същ emailTemplateId с един и същ домейн.
Но можете да имате универсален шаблон (domain = *) и специфичен за домейн шаблон за същия emailTemplateId.
Посочването на domain е уместно само ако имате различни домейни или искате да използвате специфични шаблони за тестване (domain зададен на localhost и т.н.).
Ако посочите domain, той трябва да съвпада с DomainConfig. При грешка се предоставя списък с валидни домейни.
Синтаксисът на шаблона е EJS и се визуализира с таймаут от 500ms. P99 за визуализация е <5ms, така че ако достигнете 500ms, нещо не е наред.
Вашият шаблон трябва да се визуализира с вашите дадени testData, за да се запази. Грешките при визуализация се агрегират и докладват в таблото (скоро налично чрез API).

Минималните данни, необходими за добавяне на шаблон, са следните:

Пример за минимален POST на EmailTemplate с cURL

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

Може да искате да имате шаблони за всеки сайт, в който случай дефинирате domain:

Пример за POST на EmailTemplate с cURL

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

Структура на заявката за POST на EmailTemplate

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за POST на EmailTemplate

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

Тази API крайна точка предоставя възможност за предварителен преглед на имейл шаблони.

Пример за минимален POST за предварителен преглед на EmailTemplate с cURL

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

Структура на заявката за POST на EmailTemplate

Copy

interface EmailTemplatePostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за POST на EmailTemplate

Copy

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

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

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

Този маршрут предоставя премахването на единичен EmailTemplate по id.

Пример за премахване на EmailTemplate с cURL

Copy

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

Структура на заявката за премахване на EmailTemplate

Copy

interface EmailTemplateRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на EmailTemplate

Copy

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

Структура на хаштаг

Обектът HashTag представлява таг, който може да бъде оставен от потребител. HashTags могат да се използват за свързване към външно съдържание или за свързване на свързани коментари заедно.

Структурата на обекта HashTag е следната:

Структура на HashTag

Copy

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

Забележки:

В някои API крайни точки ще видите, че хаштагът се използва в URL. Не забравяйте да URI-кодирате стойностите. Например # трябва вместо това да се представи като %23.
Някои от тези полета са маркирани като READONLY - те се връщат от API, но не могат да бъдат зададени.

GET /api/v1/hash-tags

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

Този API използва странициране, предоставено от параметъра на заявката page. HashTags се връщат на страници от 100, подредени по tag.

Пример за HashTag с cURL

Copy

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

Структура на заявката за HashTag

Copy

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

Структура на отговора за HashTag

Copy

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

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

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

Този маршрут предоставя възможност за актуализиране на единичен HashTag.

Пример за актуализация на HashTag с cURL

Copy

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

Структура на заявката за актуализация на HashTag

Copy

interface HashTagPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за актуализация на HashTag

Copy

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

POST /api/v1/hash-tags

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

Този маршрут предоставя възможност за добавяне на единичен HashTag.

Пример за създаване на HashTag с cURL

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

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за създаване на HashTag

Copy

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

POST /api/v1/hash-tags/bulk

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

Този маршрут предоставя възможност за добавяне на до 100 обекта HashTag наведнъж.

Пример за групово създаване на HashTag с cURL

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

Copy

interface HashTagPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за групово създаване на HashTag

Copy

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

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

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

Този маршрут предоставя премахването на HashTag по предоставения таг.

Имайте предвид, че освен ако автоматичното създаване на HashTag не е деактивирано, хаштаговете могат да бъдат пресъздадени от потребител, предоставящ хаштага при коментиране.

Пример за премахване на HashTag с cURL

Copy

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

Структура на заявката за премахване на HashTag

Copy

interface HashTagDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на HashTag

Copy

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

Структура на модератора

Обектът Moderator представлява конфигурация за модератор.

Има три типа модератори:

Администраторски потребители, които имат флага isCommentModeratorAdmin.
SSO потребители с флага isCommentModeratorAdmin.
Обикновени коментиращи или FastComments.com потребители, които са поканени като модератори.

Структурата Moderator се използва за представяне на състоянието на модерация за случай на употреба 3.

Ако искате да поканите потребител да бъде модератор чрез API, използвайте API Moderator, като създадете Moderator и го поканите.

Ако потребителят няма акаунт в FastComments.com, имейлът с покана ще му помогне да се настрои. Ако вече има акаунт, ще му бъде даден достъп за модерация до вашия tenant и userId на обекта Moderator ще бъде актуализиран, за да сочи към неговия потребител. Няма да имате API достъп до техния потребител, тъй като в този случай той принадлежи на самите тях и се управлява от FastComments.com.

Ако изисквате пълно управление на акаунта на потребителя, препоръчваме или да използвате SSO, или да ги добавите като Tenant потребител и след това да добавите обект Moderator, за да проследявате техните статистики.

Структурата Moderator може да се използва като механизъм за проследяване на статистики за случаи на употреба 1 и 2. След създаване на потребителя добавете обект Moderator с дефиниран userId и техните статистики ще бъдат проследявани на страницата с модератори на коментари.

Структурата на обекта Moderator е следната:

Структура на 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

Този маршрут връща единичен модератор по неговия id.

Пример за Moderator по ID с cURL

Copy

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

Структура на заявката за Moderator

Copy

interface ModeratorByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за Moderator

Copy

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

GET /api/v1/moderators

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

Този API използва странициране, предоставено от параметъра на заявката skip. Moderators се връщат на страници от 100, подредени по createdAt и id.

Цената се базира на броя върнати модератори, като струва 1 кредит на 10 върнати модератора.

Пример за Moderator с cURL

Copy

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

Структура на заявката за Moderator

Copy

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

Структура на отговора за Moderator

Copy

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

PATCH /api/v1/moderators/:id

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

Тази API крайна точка предоставя възможност за актуализиране на Moderator по id.

Актуализирането на Moderator има следните ограничения:

Следните стойности не могат да бъдат предоставени при актуализиране на Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Когато е посочен userId, този потребител трябва да съществува.
Когато е посочен userId, той трябва да принадлежи на същия tenantId, посочен в параметрите на заявката.
Двама модератори в един и същ tenant не могат да бъдат добавени с един и същ email.
Не можете да променяте tenantId, свързан с Moderator.

Пример за PATCH на Moderator с cURL

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

Структура на заявката за PATCH на Moderator

Copy

interface ModeratorPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за PATCH на Moderator

Copy

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

POST /api/v1/moderators

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

Този маршрут предоставя възможност за добавяне на единичен Moderator.

Създаването на Moderator има следните ограничения:

Винаги трябва да се предоставят name и email. userId е незадължителен.
Следните стойности не могат да бъдат предоставени при създаване на Moderator:
- acceptedInvite
- markReviewedCount
- deletedCount
- markedSpamCount
- approvedCount
- editedCount
- bannedCount
- verificationId
- createdAt
Когато е посочен userId, този потребител трябва да съществува.
Когато е посочен userId, той трябва да принадлежи на същия tenantId, посочен в параметрите на заявката.
Двама модератори в един и същ tenant не могат да бъдат добавени с един и същ email.

Можем да създадем Moderator за потребител, за който знаем само имейла:

Пример за създаване на Moderator чрез имейл с cURL

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

Или можем да създадем Moderator за потребител, който принадлежи на нашия tenant, за да проследяваме неговите статистики за модерация:

Пример за създаване на Moderator чрез Tenant потребител с cURL

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

Copy

interface ModeratorPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за създаване на Moderator

Copy

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

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

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

Този маршрут предоставя възможност за покана на единичен Moderator.

Съществуват следните ограничения за изпращане на имейл с покана на Moderator:

Moderator трябва вече да съществува.
fromName не може да бъде по-дълъг от 100 символа.

Забележки:

Ако потребител с предоставения имейл вече съществува, той ще бъде поканен да модерира коментарите на вашия tenant.
Ако потребител с предоставения имейл не съществува, връзката за покана ще го насочи през създаването на акаунта им.
Поканата ще изтече след 30 дни.

Можем да създадем Moderator за потребител, за който знаем само имейла:

Пример за покана на Moderator с cURL

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'

Това ще изпрати имейл като Bob от TenantName ви кани да бъдете модератор...

Структура на заявката за покана на Moderator

Copy

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

Структура на отговора за покана на Moderator

Copy

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

DELETE /api/v1/moderators/:id

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

Този маршрут предоставя премахването на Moderator по id.

Пример за премахване на Moderator с cURL

Copy

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

Структура на заявката за премахване на Moderator

Copy

interface ModeratorDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на Moderator

Copy

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

Структура на броя известия

Обектът NotificationCount представлява броя на непрочетените известия и метаданни за потребител.

Ако няма непрочетени известия, няма да има NotificationCount за потребителя.

Обектите NotificationCount се създават автоматично и не могат да бъдат създавани чрез API. Те също изтичат след една година.

Можете да изчистите броя на непрочетените известия на потребител, като изтриете неговия NotificationCount.

Структурата на обекта NotificationCount е следната:

Структура на NotificationCount

Copy

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

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

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

Този маршрут връща единичен NotificationCount по потребителски id. С SSO потребителският id е във формат <tenant id>:<user id>.

Ако няма непрочетени известия, няма да има NotificationCount - така че ще получите 404.

Това е различно от notifications/count по това, че е много по-бързо, но не позволява филтриране.

Пример за NotificationCount по ID с cURL

Copy

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

Структура на заявката за NotificationCount

Copy

interface NotificationCountGetQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за NotificationCount

Copy

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

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

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

Този маршрут изтрива единичен NotificationCount по потребителски id. С SSO потребителският id е във формат <tenant id>:<user id>.

Това ще изчисти броя на непрочетените известия на потребителя (червената камбанка в уиджета за коментари ще избледнее и броят ще изчезне).

Пример за DELETE на NotificationCount с cURL

Copy

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

Структура на заявката за премахване на NotificationCount

Copy

interface NotificationCountDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на NotificationCount

Copy

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

Структура на известие

Обектът Notification представлява известие за потребител.

Обектите Notification се създават автоматично и не могат да бъдат създавани чрез API. Те също изтичат след една година. Известията не могат да бъдат изтривани. Въпреки това те могат да бъдат актуализирани, за да зададете viewed на false, и можете да търсите по viewed.

Потребителят може също да се откаже от известия за конкретен коментар, като зададе optedOut в известието на true. Можете да се включите отново, като го зададете на false.

Има различни типове известия - проверете relatedObjectType и type.

Начините, по които се създават известия, са доста гъвкави и могат да бъдат задействани от много сценарии (вижте NotificationType).

Към днешна дата съществуването на Notification всъщност не означава, че имейл е или трябва да бъде изпратен. По-скоро известията се използват за емисия от известия и свързани интеграции.

Структурата на обекта Notification е следната:

Структура на Notification

Copy

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

GET /api/v1/notifications

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

Този маршрут връща до 30 обекта Notification, сортирани по createdAt, най-новите първи.

Можете да филтрирате по userId. С SSO потребителският id е във формат <tenant id>:<user id>.

Пример за непрочетени известия за потребител с cURL

Copy

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

Структура на заявката за известия

Copy

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

Структура на отговора за известия

Copy

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

GET /api/v1/notifications/count

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

Този маршрут връща обект, съдържащ броя на известията под параметър count.

Той е по-бавен от /notification-count/ и струва двойно повече кредити, но позволява филтриране по повече измерения.

Можете да филтрирате по същите параметри като крайната точка /notifications, като userId. С SSO потребителският id е във формат <tenant id>:<user id>.

Пример за брой непрочетени известия за потребител с cURL

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'

Пример за брой непрочетени известия за потребител за конкретна страница с cURL

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'

Структура на заявката за брой известия

Copy

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

Структура на отговора за брой известия

Copy

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

PATCH /api/v1/notifications/:id

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

Тази API крайна точка предоставя възможност за актуализиране на Notification по id.

Актуализирането на Notification има следните ограничения:

Можете да актуализирате само следните полета:
- viewed
- optedOut

Пример за PATCH на Notification с cURL

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

Структура на заявката за PATCH на Notification

Copy

interface NotificationPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за PATCH на Notification

Copy

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

Структура на страница

Обектът Page представлява страницата, към която могат да принадлежат много коментари. Тази връзка се определя от urlId.

Page съхранява информация като заглавието на страницата, броя на коментарите и urlId.

Структурата на обекта Page е следната:

Структура на Page

Copy

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

GET /api/v1/pages

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

В момента можете да извличате само всички страници (или единична страница чрез /by-url-id), свързани с вашия акаунт. Ако искате по-прецизно търсене, свържете се с нас.

Пример за Pages с cURL

Copy

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

Структура на заявката за Pages

Copy

interface PagesRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за Pages

Copy

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

Полезен съвет

API Comment изисква urlId. Можете първо да извикате API Pages, за да видите как изглеждат наличните за вас стойности на urlId.

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

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

Индивидуални страници могат да бъдат извлечени по съответния им urlId. Това може да бъде полезно за търсене на заглавия на страници или брой коментари.

Пример за Page по URL ID с cURL

Copy

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

Структура на заявката за Page по URL ID

Copy

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

Структура на отговора за Page по URL ID

Copy

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

Полезен съвет

Не забравяйте да URI кодирате стойности като urlId.

PATCH /api/v1/pages/:id

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

Този маршрут предоставя възможност за актуализиране на единична Page. Съответните коментари ще бъдат актуализирани.

Пример за актуализация на Page с cURL

Copy

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

Структура на заявката за актуализация на Page

Copy

interface PagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за актуализация на Page

Copy

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

Забележка

Някои параметри в обекта Page се актуализират автоматично. Това са атрибутите за брой и заглавие. Броевете не могат да бъдат актуализирани чрез API, тъй като са изчислени стойности. title на страницата може да бъде зададен чрез API, но ще бъде презаписан, ако уиджетът за коментари се използва на страница със същия urlId и различно заглавие на страницата.

POST /api/v1/pages

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

Тази API крайна точка предоставя възможност за създаване на страници.

Често срещан случай на употреба е контролът на достъпа.

Забележки:

Ако сте коментирали в нишка за коментари или сте извикали API, за да създадете Comment, вече сте създали обект Page! Можете да опитате да го извлечете чрез маршрута /by-url-id Page, подавайки същия urlId, подаден на уиджета за коментари.
Структурата Page съдържа някои изчислени стойности. В момента това са commentCount и rootCommentCount. Те се попълват автоматично и не могат да бъдат зададени от API. Опитът да направите това ще накара API да върне грешка.

Пример за POST на Page с cURL

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

Структура на заявката за POST на Page

Copy

interface PagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за POST на Page

Copy

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

DELETE /api/v1/pages/:id

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

Този маршрут предоставя премахването на единична страница по id.

Имайте предвид, че взаимодействието с уиджета за коментари за страница със същия urlId просто ще пресъздаде Page безпроблемно.

Пример за премахване на Page с cURL

Copy

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

Структура на заявката за премахване на Page

Copy

interface PageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на Page

Copy

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

Структура на чакащо уебхук събитие

Обектът PendingWebhookEvent представлява webhook събитие в опашката, което чака обработка.

Обектите PendingWebhookEvent се създават автоматично и не могат да бъдат създадени ръчно чрез API. Те също изтичат след една година. Могат да бъдат изтрити, което премахва задачата от опашката.

Има различни типове събития - проверете eventType (OutboundSyncEventType) и type (OutboundSyncType).

Често срещан случай на употреба за този API е внедряването на персонализиран мониторинг. Може да искате да извикате крайната точка /count периодично, за да проверявате броя на чакащите събития за дадени филтри.

Структурата на обекта PendingWebhookEvent е следната:

Структура на PendingWebhookEvent

Copy

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

GET /api/v1/pending-webhook-events

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

Този маршрут връща списък с чакащи webhook събития в параметър pendingWebhookEvents.

Този API използва пагинация, предоставена чрез параметъра skip. PendingWebhookEvents се връщат на страници от 100, подредени по createdAt от най-новите.

Пример за PendingWebhookEvent с cURL

Copy

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

Структура на заявката за PendingWebhookEvent

Copy

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

Структура на отговора за PendingWebhookEvent

Copy

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

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

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

Този маршрут връща обект, съдържащ броя на чакащите webhook събития в параметър count.

Можете да филтрирате по същите параметри като крайната точка /pending-webhook-events

Пример за брой PendingWebhookEvent с cURL

Copy

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

Структура на заявката за брой PendingWebhookEvent

Copy

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

Структура на отговора за брой PendingWebhookEvent

Copy

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

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

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

Този маршрут позволява изтриването на единичен PendingWebhookEvent.

Ако имате нужда от групово изтриване, извикайте GET API с пагинация и след това извикайте този API последователно.

Пример за DELETE на PendingWebhookEvent с cURL

Copy

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

Структура на заявката за изтриване на PendingWebhookEvent

Copy

interface PendingWebhookEventDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за изтриване на PendingWebhookEvent

Copy

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

Структура на SSO потребител

FastComments предоставя лесно за използване SSO решение. Актуализирането на информацията на потребител с интеграцията, базирана на HMAC, е толкова просто, колкото потребителят да зареди страницата с актуализиран payload.

Въпреки това може да е желателно да управлявате потребител извън този поток, за да подобрите последователността на вашето приложение.

API за SSO потребители предоставя начин за CRUD на обекти, които наричаме SSOUsers. Тези обекти са различни от обикновените Users и се съхраняват отделно за безопасност на типовете.

Структурата на обекта SSOUser е следната:

Структура на SSOUser

Copy

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

Фактуриране за SSO потребители

SSO потребителите се таксуват различно въз основа на техните флагове за права:

Обикновени SSO потребители: Потребители без администраторски или модераторски права се таксуват като обикновени SSO потребители
SSO администратори: Потребители с флагове isAccountOwner или isAdminAdmin се таксуват отделно като SSO администратори (същата ставка като обикновените tenant администратори)
SSO модератори: Потребители с флаг isCommentModeratorAdmin се таксуват отделно като SSO модератори (същата ставка като обикновените модератори)

Важно: За да се предотврати двойно таксуване, системата автоматично дедублира SSO потребители спрямо обикновени tenant потребители и модератори по имейл адрес. Ако SSO потребител има същия имейл като обикновен tenant потребител или модератор, той няма да бъде таксуван два пъти.

Контрол на достъпа

Потребителите могат да бъдат разделени на групи. За това служи полето groupIds и е незадължително.

@Споменавания

По подразбиране @споменаванията ще използват username за търсене на други sso потребители, когато се въведе символът @. Ако се използва displayName, тогава резултатите, съвпадащи с username, ще бъдат игнорирани, когато има съвпадение за displayName, и резултатите от търсенето на @споменаване ще използват displayName.

Абонаменти

С FastComments потребителите могат да се абонират за страница, като щракнат върху иконата на камбанката в уиджета за коментари и щракнат върху Абониране.

При обикновен потребител изпращаме имейли за известия въз основа на техните настройки за известия.

При SSO потребители разделяме това за обратна съвместимост. Потребителите ще получават тези допълнителни имейли за известия за абонамент само ако зададете optedInSubscriptionNotifications на true.

Значки

Можете да присвоявате значки на SSO потребители, като използвате свойството badgeConfig. Значките са визуални индикатори, които се появяват до името на потребителя в коментарите.

badgeIds - Масив от ID на значки за присвояване на потребителя. Те трябва да бъдат валидни ID на значки, създадени във вашия акаунт в FastComments. Ограничено до 30 значки.
override - Ако е true, всички съществуващи значки, показвани в коментарите, ще бъдат заменени с предоставените. Ако е false или е пропуснато, предоставените значки ще бъдат добавени към съществуващите значки.
update - Ако е true, свойствата за показване на значки ще бъдат актуализирани от конфигурацията на tenant всеки път, когато потребителят влезе.

GET /api/v1/sso-users

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

Този маршрут връща SSO потребители на страници от 100. Пагинацията се предоставя чрез параметъра skip. Потребителите са сортирани по тяхната signUpDate и id.

Пример за SSOUsers с cURL

Copy

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

Структура на заявката за SSOUsers

Copy

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

Структура на отговора за SSOUsers

Copy

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

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

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

Този маршрут връща единичен SSO потребител по тяхното id.

Пример за SSOUser по ID с cURL

Copy

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

Структура на заявката за SSOUser

Copy

interface SSOUserRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за SSOUser

Copy

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

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

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

Този маршрут връща единичен SSO потребител по техния имейл.

Пример за SSOUser по имейл с cURL

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

Copy

interface SSOUserRequestByEmailQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за SSOUser

Copy

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

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

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

Този маршрут предоставя възможност за актуализиране на единичен SSO потребител.

Пример за актуализиране на SSOUser с cURL

Copy

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

Структура на заявката за актуализиране на SSOUser

Copy

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

Структура на отговора за актуализиране на SSOUser

Copy

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

POST /api/v1/sso-users

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

Този маршрут предоставя създаването на единичен SSO потребител.

Опитът да създадете двама потребители с едно и също ID ще доведе до грешка.

Пример за създаване на SSOUser с cURL

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

В този пример указваме groupIds за контрол на достъпа, но това е незадължително.

Структура на заявката за създаване на SSOUser

Copy

interface SSOUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за създаване на SSOUser

Copy

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

Бележка за интеграция

Данните, подадени от API, могат да бъдат презаписани просто чрез подаване на различен SSO User HMAC payload. Например, ако зададете потребителско име чрез API, но след това подадете различно чрез SSO потока при зареждане на страницата, ние автоматично ще актуализираме потребителското му име.

Ние няма да актуализираме параметрите на потребителя в този поток, освен ако изрично не ги посочите или ги зададете на null (не undefined).

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

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

Този маршрут предоставя възможност за актуализиране на единичен SSO потребител.

Пример за актуализиране на SSOUser с cURL

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

В този пример указваме groupIds за контрол на достъпа, но това е незадължително.

Структура на заявката за актуализиране на SSOUser

Copy

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

Структура на отговора за актуализиране на SSOUser

Copy

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

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

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

Този маршрут предоставя премахване на единичен SSO потребител по неговото id.

Обърнете внимание, че зареждането на уиджета за коментари отново с payload за този потребител просто ще създаде потребителя отново безпроблемно.

Изтриването на коментарите на потребителя е възможно чрез параметъра на заявката deleteComments. Обърнете внимание, че ако това е true:

Всички коментари на потребителя ще бъдат изтрити на живо.
Всички дъщерни (сега сираци) коментари ще бъдат изтрити или анонимизирани въз основа на конфигурацията на асоциираната страница на всеки коментар. Например, ако режимът на изтриване на нишка е "anonymize", тогава отговорите ще останат, а коментарите на потребителя ще бъдат анонимизирани. Това се прилага само когато commentDeleteMode е Remove (стойността по подразбиране).
creditsCost става 2.

Анонимизирани коментари

Можете да запазите коментарите на потребителя, но просто да ги анонимизирате, като зададете commentDeleteMode=1.

Ако коментарите на потребителя са анонимизирани, следните стойности се задават на null:

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

isDeleted и isDeletedUser се задават на true.

При рендериране уиджетът за коментари ще използва DELETED_USER_PLACEHOLDER (по подразбиране: "[deleted]") за името на потребителя и DELETED_CONTENT_PLACEHOLDER за коментара. Те могат да бъдат персонализирани чрез UI за персонализиране на уиджета.

Примери

Пример за премахване на SSOUser с cURL

Copy

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

Структура на заявката за премахване на SSOUser

Copy

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

Структура на отговора за премахване на SSOUser

Copy

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

Структура на абонамент

Обектът Subscription представлява абонамент за потребител.

Обектите Subscription се създават, когато потребител кликне върху камбанката за известия в уиджета за коментари и щракне върху "Абониране за тази страница".

Абонаментите могат да бъдат създадени и чрез API.

Наличието на обект Subscription причинява генерирането на обекти Notification и изпращането на имейли, когато нови коментари са оставени в корена на асоциираната страница, за която е Subscription. Изпращането на имейли зависи от типа потребител. За обикновени потребители това зависи от optedInNotifications. За SSO потребители това зависи от optedInSubscriptionNotifications. Обърнете внимание, че някои приложения може да нямат концепцията за уеб достъпна страница, в този случай просто задайте urlId на id на елемента, за който се абонирате (същата стойност за urlId, която бихте подали на уиджета за коментари).

Структурата на обекта Subscription е следната:

Структура на Subscription

Copy

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

GET /api/v1/subscriptions/:id

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

Този маршрут връща до 30 обекта Subscription, сортирани по createdAt, от най-новите.

Можете да филтрирате по userId. При SSO потребителският id е във формат <tenant id>:<user id>.

Пример за абонаменти на потребител с cURL

Copy

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

Структура на заявката за Subscriptions

Copy

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

Структура на отговора за Subscriptions

Copy

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

POST /api/v1/subscriptions

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

Тази API крайна точка предоставя възможност за създаване на Subscription. Обърнете внимание, че потребител може да има само един абонамент на страница, тъй като повече е излишно, и опитът да създадете повече от един абонамент за един и същи потребител за една и съща страница ще доведе до грешка.

Създаването на абонамент ще доведе до създаването на обекти Notification, когато нов коментар е оставен в корена на абонирания urlId (когато parentId на коментара е null).

Пример за POST на Subscription с cURL

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

Структура на заявката за POST на Subscription

Copy

interface SubscriptionPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за POST на Subscription

Copy

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

DELETE /api/v1/subscriptions/:id

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

Този маршрут изтрива единичен обект Subscription по id.

Пример за премахване на Subscription с cURL

Copy

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

Структура на заявката за премахване на Subscription

Copy

interface SubscriptionsDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на Subscription

Copy

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

Структура на дневната употреба на тенанта

Обектът TenantDailyUsage представлява използването за tenant за даден ден. Ако няма активност за даден tenant за даден ден, този ден няма да има обект TenantDailyUsage.

Обектът TenantDailyUsage не е в реално време и може да е с минути назад от действителното използване.

Структурата на обекта TenantDailyUsage е следната:

Структура на 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
    /** Ignored for billing. **/
    ignored: boolean
}

GET /api/v1/tenant-daily-usage

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

Този маршрут позволява търсене на използването на tenant по година, месец и ден. Могат да бъдат върнати до 365 обекта, а цената е 1 api кредит на 10 обекта.

Обектите в отговора са сортирани по датата, на която са създадени (най-старите първо).

Пример за търсене на TenantDailyUsage с cURL

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

Copy

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

Структура на отговора за TenantDailyUsage

Copy

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

Структура на тенант

Tenant дефинира клиент на FastComments.com. Те могат да бъдат създадени чрез API от tenant-и с достъп до white labeling. White labeled tenant-и не могат да създават други white labeled tenant-и (позволено е само едно ниво на влагане).

Структурата на обекта Tenant е следната:

Структура на Tenant

Copy

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

GET /api/v1/tenants/:id

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

Този маршрут връща единичен Tenant по id.

Пример за Tenant по ID с cURL

Copy

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

Структура на заявката за Tenant

Copy

interface TenantByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за Tenant

Copy

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

GET /api/v1/tenants

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

Този API връща tenant-и, които се управляват от вашия tenant.

Пагинацията се предоставя чрез параметъра на заявката skip. Tenant-ите се връщат на страници от 100, подредени по signUpDate и id.

Цената се базира на броя върнати tenant-и, струващи 1 кредит на 10 върнати tenant-а.

Пример за Tenant с cURL

Copy

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

Можете да дефинирате meta параметри на обектите Tenant и да търсите съвпадащи tenant-и. Например, за ключа someKey и мета стойността some-value, можем да конструираме JSON обект с тази двойка ключ/стойност и след това да го URI кодираме като параметър на заявката за филтриране:

Пример за заявка на Tenant по Meta с cURL

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

Copy

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

Структура на отговора за Tenant

Copy

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

POST /api/v1/tenants

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

Този маршрут предоставя възможност за добавяне на единичен Tenant.

Създаването на Tenant има следните ограничения:

name е задължително.
domainConfiguration е задължително.
Следните стойности не могат да бъдат предоставени при създаване на Tenant:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
signUpDate не може да бъде в бъдещето.
name не може да бъде по-дълго от 200 символа.
email не може да бъде по-дълго от 300 символа.
email трябва да бъде уникален за всички tenant-и на FastComments.com.
Не можете да създавате tenant-и, ако родителският tenant няма дефиниран валиден TenantPackage.
- Ако вашият tenant е бил създаден чрез FastComments.com, това не би трябвало да е проблем.
Не можете да създавате повече tenant-и от дефинираното под maxWhiteLabeledTenants във вашия пакет.
Трябва да посочите параметъра на заявката tenantId, който е id на вашия родителски tenant с активиран white labeling.

Можем да създадем Tenant само с няколко параметъра:

Пример за създаване на Tenant с cURL

Copy

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

Структура на заявката за създаване на Tenant

Copy

interface TenantPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за създаване на Tenant

Copy

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

PATCH /api/v1/tenants/:id

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

Тази API крайна точка предоставя възможност за актуализиране на Tenant по id.

Актуализирането на Tenant има следните ограничения:

Следните стойности не могат да бъдат актуализирани:
- hasFlexPricing
- lastBillingIssueReminderDate
- flexLastBilledAmount
- managedByTenantId
signUpDate не може да бъде в бъдещето.
name не може да бъде по-дълго от 200 символа.
email не може да бъде по-дълго от 300 символа.
email трябва да бъде уникален за всички tenant-и на FastComments.com.
Когато задавате billingInfoValid на true, billingInfo трябва да бъде предоставен в същата заявка.
Не можете да актуализирате packageId, асоцииран с вашия собствен tenant.
Не можете да актуализирате paymentFrequency, асоциирана с вашия собствен tenant.

Пример за PATCH на Tenant с cURL

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

Структура на заявката за PATCH на Tenant

Copy

interface TenantPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за PATCH на Tenant

Copy

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

DELETE /api/v1/tenants/:id

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

Този маршрут предоставя премахване на Tenant и всички свързани данни (потребители, коментари и т.н.) по id.

Съществуват следните ограничения около премахването на tenant-и:

Tenant-ът трябва да е ваш собствен или white labeled tenant, който управлявате.
Параметърът на заявката sure трябва да е зададен на true.

Пример за премахване на Tenant с cURL

Copy

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

Структура на заявката за премахване на Tenant

Copy

interface TenantDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на Tenant

Copy

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

Структура на пакет на тенанта

TenantPackage дефинира информация за пакет, достъпна за Tenant. Tenant може да има много налични пакети, но само един в употреба в даден момент.

Tenant не може да се използва за никакви продукти, докато неговият packageId не сочи към валиден TenantPackage.

Има два типа обекти TenantPackage:

Пакети с фиксирана цена - където hasFlexPricing е false.
Гъвкаво ценообразуване - където hasFlexPricing е true.

И в двата случая се дефинират лимити на акаунта, използващ пакета, но при Flex tenant-ът се таксува базова цена плюс това, което е използвал, дефинирано от flex* параметрите.

Tenant може да има множество tenant пакети и да има възможност сам да променя пакета от страницата за информация за фактуриране.

Ако ще се справяте сами с фактурирането за tenant-и, все пак ще трябва да дефинирате пакет за всеки tenant, за да дефинирате техните лимити. Просто задайте billingHandledExternally на true за Tenant и те няма да могат сами да променят своята информация за фактуриране или активен пакет.

Не можете да създавате пакети с по-високи лимити от родителския tenant.

Структурата на обекта TenantPackage е следната:

Структура на 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 // Cost per regular SSO user (without admin/moderator permissions)
    flexSSOUserUnit?: null
    flexAPICreditCostCents?: null
    flexAPICreditUnit?: null
    flexModeratorCostCents?: null
    flexModeratorUnit?: null
    flexAdminCostCents?: null
    flexAdminUnit?: null
    flexDomainCostCents?: null
    flexDomainUnit?: null
    flexSSOAdminCostCents?: null // Cost per SSO user with admin permissions (isAccountOwner or isAdminAdmin flags)
    flexSSOAdminUnit?: null
    flexSSOModeratorCostCents?: null // Cost per SSO user with moderator permissions (isCommentModeratorAdmin flag)
    flexSSOModeratorUnit?: null
    flexMinimumCostCents?: null
}

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

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

Този маршрут връща единичен Tenant Package по id.

Пример за TenantPackage по ID с cURL

Copy

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

Структура на заявката за TenantPackage

Copy

interface TenantPackageByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за TenantPackage

Copy

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

GET /api/v1/tenant-packages

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

Този API използва пагинация, предоставена чрез параметъра на заявката skip. TenantPackages се връщат на страници от 100, подредени по createdAt и id.

Цената се базира на броя върнати tenant пакети, струващи 1 кредит на 10 върнати tenant пакета.

Пример за TenantPackage с cURL

Copy

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

Структура на заявката за TenantPackage

Copy

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

Структура на отговора за TenantPackage

Copy

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

POST /api/v1/tenant-packages

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

Този маршрут предоставя възможност за добавяне на единичен TenantPackage.

Създаването на TenantPackage има следните ограничения:

Следните параметри са задължителни:
- name
- tenantId
- monthlyCostUSD - Може да бъде null.
- yearlyCostUSD - Може да бъде null.
- maxMonthlyPageLoads
- maxMonthlyAPICredits
- maxMonthlyComments
- maxConcurrentUsers
- maxTenantUsers
- maxSSOUsers
- maxModerators
- maxDomains
- hasDebranding
- forWhoText
- featureTaglines
- hasFlexPricing - Ако е true, тогава всички flex* параметри са задължителни.
name не може да бъде по-дълго от 50 символа.
Всеки елемент на forWhoText не може да бъде по-дълъг от 200 символа.
Всеки елемент на featureTaglines не може да бъде по-дълъг от 100 символа.
TenantPackage трябва да бъде "по-малък" от родителския tenant. Например, всички max* параметри трябва да имат по-ниски стойности от родителския tenant.
White labeled tenant може да има максимум пет пакета.
Само tenant-и с достъп до white labeling могат да създават TenantPackage.
Не можете да добавяте пакети към вашия собствен tenant. :)

Можем да създадем TenantPackage по следния начин:

Пример за създаване на TenantPackage с cURL

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

Copy

interface TenantPackagePostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за създаване на TenantPackage

Copy

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

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

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

Тази API крайна точка предоставя възможност за актуализиране на TenantPackage по id.

Актуализирането на TenantPackage има следните ограничения:

Ако задавате hasFlexPricing на true, тогава всички flex* параметри са задължителни в същата заявка.
name не може да бъде по-дълго от 50 символа.
Всеки елемент на forWhoText не може да бъде по-дълъг от 200 символа.
Всеки елемент на featureTaglines не може да бъде по-дълъг от 100 символа.
TenantPackage трябва да бъде "по-малък" от родителския tenant. Например, всички max* параметри трябва да имат по-ниски стойности от родителския tenant.
Не можете да променяте tenantId, асоцииран с TenantPackage.

Пример за PATCH на TenantPackage с cURL

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

Структура на заявката за PATCH на TenantPackage

Copy

interface TenantPackagePatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за PATCH на TenantPackage

Copy

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

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

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

Този маршрут предоставя премахване на TenantPackage по id.

Не можете да премахнете TenantPackage, който се използва (packageId на tenant сочи към пакета). Първо актуализирайте Tenant.

Пример за премахване на TenantPackage с cURL

Copy

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

Структура на заявката за премахване на TenantPackage

Copy

interface TenantPackageDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на TenantPackage

Copy

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

Структура на потребител на тенанта

TenantUser дефинира User, който се управлява от конкретен tenant. Акаунтът им е под пълен контрол на tenant-а, с който са асоциирани, и техният акаунт може да бъде актуализиран или изтрит чрез UI или API.

Tenant потребителите могат да бъдат администратори с всички права и достъп до Tenant, или могат да бъдат ограничени до конкретни права за модериране на коментари, достъп до API ключове и т.н.

Структурата на обекта TenantUser е следната:

Структура на TenantUser

Copy

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

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

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

Този маршрут връща единичен TenantUser по id.

Пример за TenantUser по ID с cURL

Copy

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

Структура на заявката за TenantUser

Copy

interface TenantUserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за TenantUser

Copy

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

GET /api/v1/tenant-users

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

Този API използва пагинация, предоставена чрез параметъра на заявката skip. TenantUsers се връщат на страници от 100, подредени по signUpDate, username и id.

Цената се базира на броя върнати tenant потребители, струващи 1 кредит на 10 върнати tenant потребители.

Пример за TenantUser с cURL

Copy

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

Структура на заявката за TenantUser

Copy

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

Структура на отговора за TenantUser

Copy

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

POST /api/v1/tenant-users

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

Този маршрут предоставя възможност за добавяне на единичен TenantUser.

Създаването на TenantUser има следните ограничения:

username е задължително.
email е задължително.
signUpDate не може да бъде в бъдещето.
locale трябва да бъде в списъка на Поддържани локали.
username трябва да бъде уникално в целия FastComments.com. Ако това е проблем, предлагаме да използвате SSO вместо това.
email трябва да бъде уникален в целия FastComments.com. Ако това е проблем, предлагаме да използвате SSO вместо това.
Не можете да създавате повече tenant потребители от дефинираното под maxTenantUsers във вашия пакет.

Можем да създадем TenantUser по следния начин

Пример за създаване на TenantUser с cURL

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

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за създаване на TenantUser

Copy

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

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

Този маршрут предоставя възможност за изпращане на линк за вход на единичен TenantUser.

Полезно е при групово създаване на потребители, без да се налага да им обяснявате как да влязат във FastComments.com. Това просто ще им изпрати "магически линк" за вход, който изтича след 30 дни.

Съществуват следните ограничения за изпращане на линк за вход на TenantUser:

TenantUser трябва вече да съществува.
Трябва да имате достъп за управление на Tenant, към който принадлежи TenantUser.

Можем да изпратим линк за вход на TenantUser по следния начин:

Пример за линк за вход на TenantUser с cURL

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'

Това ще изпрати имейл като Bob от TenantName ви кани да бъдете модератор...

Структура на заявката за линк за вход на TenantUser

Copy

interface TenantUserPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за линк за вход на TenantUser

Copy

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

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

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

Този маршрут предоставя възможност за актуализиране на единичен TenantUser.

Актуализирането на TenantUser има следните ограничения:

signUpDate не може да бъде в бъдещето.
locale трябва да бъде в списъка на Поддържани локали.
username трябва да бъде уникално в целия FastComments.com. Ако това е проблем, предлагаме да използвате SSO вместо това.
email трябва да бъде уникален в целия FastComments.com. Ако това е проблем, предлагаме да използвате SSO вместо това.
Не можете да актуализирате tenantId на потребител.

Можем да създадем TenantUser по следния начин

Пример за актуализиране на TenantUser с cURL

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

Copy

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

Структура на отговора за актуализиране на TenantUser

Copy

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

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

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

Този маршрут предоставя премахване на TenantUser по id.

Всички коментари на потребителя ще бъдат изтрити на живо.
Всички дъщерни (сега сираци) коментари ще бъдат изтрити или анонимизирани въз основа на конфигурацията на асоциираната страница на всеки коментар. Например, ако режимът на изтриване на нишка е "anonymize", тогава отговорите ще останат, а коментарите на потребителя ще бъдат анонимизирани. Това се прилага само когато commentDeleteMode е Remove (стойността по подразбиране).
creditsCost става 2.

Анонимизирани коментари

Можете да запазите коментарите на потребителя, но просто да ги анонимизирате, като зададете commentDeleteMode=1.

Ако коментарите на потребителя са анонимизирани, следните стойности се задават на null:

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

isDeleted и isDeletedUser се задават на true.

Примери

Пример за премахване на TenantUser с cURL

Copy

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

Структура на заявката за премахване на TenantUser

Copy

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

Структура на отговора за премахване на TenantUser

Copy

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

Структура на потребителя

User е обект, който представлява най-общ знаменател на всички потребители.

Имайте предвид, че във FastComments имаме множество различни случаи на употреба за потребители:

Сигурно SSO
Просто SSO
Tenant потребители (Например: Администратори)
Коментатори

Този API е за Коментатори и потребители, създадени чрез Просто SSO. По същество всеки потребител, създаден чрез вашия сайт, може да бъде достъпен чрез този API. Tenant потребители също могат да бъдат извлечени по този начин, но ще получите повече информация, като взаимодействате с API /tenant-users/.

За Сигурно SSO моля използвайте API /sso-users/.

Не можете да актуализирате тези типове потребители. Те са създали акаунта си чрез вашия сайт, така че предоставяме някакъв базов достъп само за четене, но не можете да правите промени. Ако искате да имате такъв тип поток - трябва да настроите Сигурно SSO.

Структурата на обекта User е следната:

Структура на User

Copy

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

GET /api/v1/users/:id

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

Този маршрут връща единичен User по id.

Пример за User по ID с cURL

Copy

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

Структура на заявката за User

Copy

interface UserByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за User

Copy

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

Структура на глас

Обектът Vote представлява глас, оставен от потребител.

Връзката между коментари и глас се дефинира чрез commentId.

Структурата на обекта Vote е следната:

Структура на 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

Гласовете трябва да бъдат извлечени по urlId.

Типове гласове

Има три типа гласове:

Удостоверени гласове, които се прилагат към съответния коментар. Можете да ги създадете чрез този API.
Удостоверени гласове, които са в очакване на верификация и следователно все още не са приложени към коментара. Те се създават, когато потребител използва механизма влизане за гласуване на FastComments.com.
Анонимни гласове, които се прилагат към съответния коментар. Те се създават заедно с анонимното коментиране.

Те се връщат в отделни списъци в API, за да се намали объркването.

Пример за Votes с cURL

Copy

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

Структура на заявката за Votes

Copy

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

Структура на отговора за Votes

Copy

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

Бележки за анонимни гласове

Обърнете внимание, че анонимните гласове, създадени чрез този API, ще се появят в списъка appliedAuthorizedVotes. Те се считат за оторизирани, тъй като са създадени чрез API с API ключ.

Структурата appliedAnonymousVotes е за гласове, създадени без имейл, API ключ и т.н.

GET /api/v1/votes/for-user

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

Позволява извличане на гласове, оставени от потребител за даден urlId. Приема userId, който може да бъде всеки потребител на FastComments.com или SSO User.

Това е полезно, ако искате да покажете дали потребител е гласувал за коментар. Когато извличате коментари, просто извикайте този API едновременно за потребителя със същия urlId.

Ако използвате анонимно гласуване, ще искате да подадете anonUserId вместо това.

Пример за Votes за потребител с cURL

Copy

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

Пример за Votes за анонимен потребител с cURL

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'

Обърнете внимание, че анонимните гласове ще се появят в списъка appliedAuthorizedVotes. Те се считат за оторизирани, тъй като са създадени чрез API с API ключ.

Структура на заявката за Votes за потребител

Copy

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

Структура на отговора за Votes за потребител

Copy

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

POST /api/v1/votes

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

Този маршрут предоставя възможност за добавяне на единичен оторизиран Vote. Гласовете могат да бъдат up (+1) или down (-1).

Пример за създаване на Vote с cURL

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'

Пример за създаване на анонимен Vote с cURL

Copy

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

Структура на заявката за създаване на Vote

Copy

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

Структура на отговора за създаване на Vote

Copy

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

Създаване на анонимни гласове

Анонимни гласове могат да бъдат създадени чрез задаване на anonUserId в параметрите на заявката вместо userId.

Този id не трябва да съответства на потребителски обект никъде (оттук анонимен). Това е просто идентификатор за сесията, така че да можете да извлечете гласовете отново в същата сесия, за да проверите дали даден коментар е бил гласуван.

Ако нямате такова нещо като "анонимни сесии" както FastComments - можете просто да зададете това на случаен ID, като UUID (въпреки че оценяваме по-малки идентификатори за спестяване на място).

Други бележки

Този API се подчинява на настройките на ниво tenant. Например, ако деактивирате гласуването за дадена страница и се опитате да създадете глас чрез API, то ще се провали с код на грешка voting-disabled.
Този API е на живо по подразбиране.
Този API ще актуализира votes на съответния Comment.

DELETE /api/v1/votes/:id

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

Този маршрут предоставя възможност за изтриване на единичен Vote.

Пример за изтриване на Vote с cURL

Copy

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

Структура на заявката за изтриване на Vote

Copy

interface VoteDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за изтриване на Vote

Copy

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

Бележки:

Този API се подчинява на настройките на ниво tenant. Например, ако деактивирате гласуването за дадена страница и се опитате да създадете глас чрез API, то ще се провали с код на грешка voting-disabled.
Този API е на живо по подразбиране.
Този API ще актуализира votes на съответния Comment.

Структура на конфигурация на домейн

Обектът DomainConfig представлява конфигурация за домейн за tenant.

Структурата на обекта DomainConfig е следната:

Структура на Domain Config

Copy

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

Структура на DKIM Config

Copy

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

За удостоверяване

Конфигурацията на домейна се използва за определяне кои сайтове могат да хостват уиджета FastComments за вашия акаунт. Това е основна форма на удостоверяване, което означава, че добавянето или премахването на каквито и да е конфигурации на домейни може да повлияе на наличността на вашата инсталация на FastComments в продукция.

Не премахвайте или актуализирайте свойството domain на Domain Config за домейн, който в момента се използва, освен ако деактивирането на този домейн е предвидено.

Това има същото поведение като премахването на домейн от /auth/my-account/configure-domains.

Също така имайте предвид, че премахването на домейн от потребителския интерфейс My Domains ще премахне всяка съответна конфигурация за този домейн, която може да е била добавена чрез този потребителски интерфейс.

За персонализация на имейли

Връзката за отписване в долния колонтитул на имейла и функцията за отписване с едно щракване, предлагана от много имейл клиенти, могат да бъдат конфигурирани чрез този API, като дефинирате съответно footerUnsubscribeURL и emailHeaders.

За DKIM

След като дефинирате вашите DKIM DNS записи, просто актуализирайте DomainConfig с вашата DKIM конфигурация, като използвате дефинираната структура.

GET /api/v1/domain-configs

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

Този API предоставя възможност за извличане на всички обекти DomainConfig за tenant.

Пример за GET на DomainConfig с cURL

Copy

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

Структура на заявката за GET на DomainConfig

Copy

interface GetDomainConfigsRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за GET на DomainConfig

Copy

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

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

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

Индивидуални DomainConfigs могат да бъдат извлечени по съответния им domain.

Пример за Domain Config по домейн с cURL

Copy

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

Структура на заявката за Domain Config по домейн

Copy

interface DomainConfigsByDomainRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за Domain Config по домейн

Copy

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

POST /api/v1/domain-configs

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

Тази API крайна точка предоставя възможност за създаване на конфигурации на домейни.

Добавянето на конфигурация за домейн оторизира този домейн за акаунта FastComments.

Често срещани случаи на употреба на този API са първоначална настройка, ако се желае добавяне на много домейни, или персонализирана конфигурация за изпращане на имейли.

Пример за POST на DomainConfig с cURL

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

Структура на заявката за POST на DomainConfig

Copy

interface DomainConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за POST на DomainConfig

Copy

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

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

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

Тази API крайна точка предоставя възможност за актуализиране на конфигурация на домейн, като посочите само домейна и атрибута за актуализиране.

Пример за PATCH на DomainConfig с cURL

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

Структура на заявката за PATCH на DomainConfig

Copy

interface DomainConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за PATCH на DomainConfig

Copy

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

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

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

Тази API крайна точка предоставя възможност за замяна на конфигурация на домейн.

Пример за PUT на DomainConfig с cURL

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

Структура на заявката за PUT на DomainConfig

Copy

interface DomainConfigPutQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за PUT на DomainConfig

Copy

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

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

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

Този маршрут предоставя премахването на единичен DomainConfig по id.

Забележка: Премахването на DomainConfig ще деоторизира този домейн от използването на FastComments.
Забележка: Повторното добавяне на домейн чрез потребителския интерфейс ще пресъздаде обекта (само с попълнен domain).

Пример за премахване на DomainConfig с cURL

Copy

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

Структура на заявката за премахване на DomainConfig

Copy

interface DomainConfigRequestQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на DomainConfig

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
}

Структура на конфигурация на въпрос

FastComments предоставя начин за конструиране на въпроси и агрегиране на техните резултати. Пример за въпрос (наричан по-нататък QuestionConfig) може да бъде звездна оценка, плъзгач или NPS въпрос (определен чрез type).

Данните от въпросите могат да бъдат агрегирани индивидуално, заедно, във времето, общо, по страница и така нататък.

Рамката има всички възможности, необходими за изграждане на уиджети от клиентска страна (с вашия сървър пред този API), административни табла и инструменти за отчетност.

Първо трябва да дефинираме QuestionConfig. Структурата е следната:

Структура на QuestionConfig

Copy

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

GET /api/v1/question-configs

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

Този маршрут връща до 100 обекта QuestionConfig наведнъж, пагинирани. Цената е 1 за всеки 100 обекта. Те са сортирани по текста на въпроса във възходящ ред (поле question).

Пример за QuestionConfig

Copy

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

Структура на заявката за QuestionConfig

Copy

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

Структура на отговора за QuestionConfig

Copy

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

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

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

Този маршрут връща единичен QuestionConfig по неговото id.

Пример за QuestionConfig по ID с cURL

Copy

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

Структура на заявката за QuestionConfig

Copy

interface QuestionConfigRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за QuestionConfig

Copy

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

POST /api/v1/question-configs

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

Тази API крайна точка предоставя възможност за създаване на QuestionConfig.

Пример за POST на QuestionConfig с cURL

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

Структура на заявката за POST на QuestionConfig

Copy

interface QuestionConfigPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за POST на QuestionConfig

Copy

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

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

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

Този маршрут предоставя възможност за актуализиране на единичен QuestionConfig.

Следната структура представлява всички стойности, които могат да бъдат променени:

Структура на QuestionConfig

Copy

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

Пример за актуализиране на QuestionConfig с cURL

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

Copy

interface QuestionConfigPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за актуализиране на QuestionConfig

Copy

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

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

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

Този маршрут предоставя премахване на QuestionConfig по id.

Това ще изтрие всички съответни резултати от въпроси (но не и коментарите). Това е част от високата цена на кредитите.

Пример за премахване на QuestionConfig с cURL

Copy

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

Структура на заявката за премахване на QuestionConfig

Copy

interface QuestionConfigDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на QuestionConfig

Copy

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

Структура на резултат от въпрос

За да запазите резултати от въпроси, създавате QuestionResult. След това можете да агрегирате резултатите от въпросите и също да ги свържете с коментари за целите на отчетността.

Структура на 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

Този маршрут връща до 1000 обекта QuestionResults наведнъж, пагинирани. Цената е 1 за всеки 100 обекта. Те са сортирани по createdAt, във възходящ ред. Можете да филтрирате по различни параметри.

Пример за QuestionResults

Copy

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

Структура на заявката за QuestionResults

Copy

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

Структура на отговора за QuestionResults

Copy

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

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

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

Този маршрут връща единичен QuestionResult по неговото id.

Пример за QuestionResult по ID с cURL

Copy

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

Структура на заявката за QuestionResult

Copy

interface QuestionResultRequestByIdQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за QuestionResult

Copy

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

POST /api/v1/question-results

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

Тази API крайна точка предоставя възможност за създаване на QuestionResult.

Пример за POST на QuestionResult с cURL

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

Структура на заявката за POST на QuestionResult

Copy

interface QuestionResultPostQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за POST на QuestionResult

Copy

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

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

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

Този маршрут предоставя възможност за актуализиране на единичен QuestionResult.

Следната структура представлява всички стойности, които могат да бъдат променени:

Структура на QuestionResult

Copy

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

Пример за актуализиране на QuestionResult с cURL

Copy

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

Структура на заявката за актуализиране на QuestionResult

Copy

interface QuestionResultPatchQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за актуализиране на QuestionResult

Copy

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

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

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

Този маршрут предоставя премахване на QuestionResult по id.

Пример за премахване на QuestionResult с cURL

Copy

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

Структура на заявката за премахване на QuestionResult

Copy

interface QuestionResultDeleteQueryParams {
    tenantId: string
    API_KEY: string
}

Структура на отговора за премахване на QuestionResult

Copy

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

GET /api/v1/question-results-aggregate

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

Тук се извършва агрегирането на резултати.

Структурата на отговора за агрегиране е следната:

Структура на QuestionResultsAggregationResult

Copy

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

Ето наличните параметри на заявката за агрегиране:

Структура на заявката за QuestionResultsAggregation

Copy

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

Ето примерна заявка:

Пример за 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'

Примерен отговор:

Примерен отговор за 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
    }

Структура на отговора за QuestionResultsAggregation

Copy

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

Бележки за производителност

При пропуск на кеша агрегациите обикновено отнемат пет секунди на милион резултата.
В противен случай заявките са с константно време.

Бележки за кеширане и цена

Когато е указано forceRecalculate, цената винаги е 10 вместо нормалните 2.
Ако кешът изтече и данните се преизчисляват, цената все още е константа 2, ако forceRecalculate не е указано. Кешът изтича въз основа на размера на агрегирания набор от данни (може да варира между 30 секунди и 5 минути).
Това е за да се стимулира използването на кеша.

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

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

Тук се извършва комбинирането на резултати с коментари. Полезно е за създаване на диаграма "скорошни положителни и отрицателни коментари" за продукт, например.

Можете да търсите чрез диапазон от стойности (включително), един или повече въпроса и по начална дата (включително).

Структурата на отговора е следната:

Структура на 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 {
    /** A date string representing when this data was calculated, since it might come from cache. **/
    createdAt: string
    results: CommentAndResult[]
}

Ето наличните параметри на заявката за агрегиране:

Структура на заявката за QuestionResultsCombineComments

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
}

Ето примерна заявка:

Пример за 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'

Примерен отговор:

Примерен отговор за 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
            }
        }
    ]
}

Структура на отговора за QuestionResultsCombineComments

Copy

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

Бележки за кеширане и цена

Когато е указано forceRecalculate, цената винаги е 10 вместо нормалните 2.
Ако кешът изтече и данните се преизчисляват, цената все още е константа 2, ако forceRecalculate не е указано.
Това е за да се стимулира използването на кеша.

Структура на потребителска значка

UserBadge е обект, който представлява значка, присвоена на потребител в системата FastComments.

Значки могат да бъдат присвоявани на потребители автоматично въз основа на тяхната активност (като брой коментари, време за отговор, ветерански статус) или ръчно от администраторите на сайта.

Структурата на обекта UserBadge е следната:

Структура на UserBadge

Copy

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

GET /api/v1/user-badges

Тази крайна точка ви позволява да извличате потребителски значки въз основа на различни критерии.

Примерна заявка:

Пример за GET заявка

Copy

Run

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

Можете да добавите различни параметри на заявката за филтриране на резултатите:

userId - Вземете значки за конкретен потребител
badgeId - Вземете инстанции на конкретна значка
type - Филтриране по тип значка (0=CommentCount, 1=CommentUpVotes, 2=CommentReplies и т.н. Вижте структурата на UserBadge за пълен списък)
displayedOnComments - Филтриране по това дали значката се показва в коментарите (true/false)
limit - Максимален брой значки за връщане (по подразбиране 30, максимум 200)
skip - Брой значки за пропускане (за пагинация)

Примерен отговор:

Отговор

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

Възможни отговори за грешка:

Грешка: Липсващ Tenant ID

Copy

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

Грешка: Невалиден лимит

Copy

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

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

Тази крайна точка ви позволява да извлечете конкретна потребителска значка по нейния уникален ID.

Примерна заявка:

Пример за GET заявка

Copy

Run

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

Примерен отговор:

Отговор

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

Възможни отговори за грешка:

Грешка: Липсващ Tenant ID

Copy

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

Грешка: Не е намерено

Copy

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

POST /api/v1/user-badges

Тази крайна точка ви позволява да създадете ново присвояване на потребителска значка.

Примерна заявка:

Пример за POST заявка

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

Тялото на заявката трябва да съдържа следните параметри:

userId (задължително) - ID на потребителя, на когото да се присвои значката
badgeId (задължително) - ID на значката за присвояване
displayedOnComments (незадължително) - Дали значката да се показва в коментарите на потребителя (по подразбиране true)

Важни бележки:

Значката трябва да съществува и да е активирана в каталога на значките на вашия tenant
Можете да присвоявате значки само на потребители, които принадлежат към вашия tenant или са коментирали на вашия сайт

Примерен отговор:

Отговор

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

Възможни отговори за грешка:

Грешка: Липсващ Tenant ID

Copy

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

Грешка: Липсващ User ID

Copy

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

Грешка: Липсващ Badge ID

Copy

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

Грешка: Значката не е намерена

Copy

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

Грешка: Неоторизиран потребител

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

Тази крайна точка ви позволява да актуализирате присвояване на потребителска значка.

В момента единственото свойство, което може да бъде актуализирано, е displayedOnComments, което контролира дали значката се показва в коментарите на потребителя.

Примерна заявка:

Пример за PUT заявка

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

Примерен отговор:

Отговор

Copy

{
  "status": "success"
}

Възможни отговори за грешка:

Грешка: Липсващ Tenant ID

Copy

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

Грешка: Липсващ ID

Copy

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

Грешка: Не е намерено

Copy

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

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

Тази крайна точка ви позволява да изтриете присвояване на потребителска значка.

Примерна заявка:

Пример за DELETE заявка

Copy

Run

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

Примерен отговор:

Отговор

Copy

{
  "status": "success"
}

Възможни отговори за грешка:

Грешка: Липсващ Tenant ID

Copy

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

Грешка: Липсващ ID

Copy

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

Грешка: Не е намерено

Copy

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

Структура на напредъка на потребителска значка

UserBadgeProgress е обект, който представлява напредъка на потребител към спечелване на различни значки в системата FastComments.

Това проследяване помага да се определи кога потребителите трябва да получат автоматични значки въз основа на тяхната активност и участие във вашата общност.

Структурата на обекта UserBadgeProgress е следната:

Структура на UserBadgeProgress

Copy

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

GET /api/v1/user-badge-progress

Тази крайна точка ви позволява да извличате записи за напредък на потребителски значки въз основа на различни критерии.

Примерна заявка:

Пример за GET заявка

Copy

Run

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

Можете да добавите различни параметри на заявката за филтриране на резултатите:

userId - Вземете напредъка за конкретен потребител
limit - Максимален брой записи за връщане (по подразбиране 30, максимум 200)
skip - Брой записи за пропускане (за пагинация)

Примерен отговор:

Отговор

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

Възможни отговори за грешка:

Грешка: Липсващ Tenant ID

Copy

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

Грешка: Невалиден лимит

Copy

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

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

Тази крайна точка ви позволява да извлечете конкретен запис за напредък на потребителска значка по неговия уникален ID.

Примерна заявка:

Пример за GET заявка

Copy

Run

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

Примерен отговор:

Отговор

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

Възможни отговори за грешка:

Грешка: Липсващ Tenant ID

Copy

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

Грешка: Не е намерено

Copy

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

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

Тази крайна точка ви позволява да извлечете запис за напредък на значка на потребител по техния потребителски ID.

Примерна заявка:

Пример за GET заявка

Copy

Run

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

Примерен отговор:

Отговор

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

Възможни отговори за грешка:

Грешка: Липсващ Tenant ID

Copy

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

Грешка: Липсващ User ID

Copy

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

Грешка: Не е намерено

Copy

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

В заключение

Надяваме се, че нашата API документация е била изчерпателна и лесна за разбиране. Ако откриете пропуски, уведомете ни по-долу.

Език 🇧🇬 Български

Ресурси на API

Агрегации

Аудитни записи

Коментари

Шаблони за имейли

Хаштагове

Модератори

Брой известия

Известия

Страници

Очакващи уебхук събития

SSO потребители

Абонаменти

Дневна употреба на тенанта

Тенанти

Пакети на тенанта

Потребители на тенанта

Потребители

Гласове

Конфигурации на домейн

Конфигурации на въпроси

Резултати от въпроси

Агрегация на резултатите от въпроси

Потребителски значки

Напредък на потребителските значки

The FastComments API

Generated SDKs

Authentication

Security Note

Authentication Option One - Headers

Authentication Option Two - Query Parameters

Ресурси на API

Използване на ресурси

Забележка!

Обобщете данните си

Примери

Пример: Брой уникални

Пример: Брой различни

Пример: Сума на стойности от множество полета

Пример: Средна стойност на множество полета

Пример: Минимални/Максимални стойности на множество полета

Пример: Брой уникални стойности на множество полета

Пример: Създаване на заявка

Пример: Брой коментари, чакащи преглед

Пример: Разбивка на одобрени, прегледани и спам коментари

Структури

Структура на AuditLog

GET /api/v1/audit-logs

Структура на коментара

Структура на текста на коментара

Отбелязване

Хаштагове

GET /api/v1/comments

Странициране

Нишки

Обяснение на дърветата

Извличане на коментари в контекста на потребител

Получаване на коментари като дърво

Получаване на коментари като дърво, търсене по хаштаг

Всички параметри на заявката

Отговорът

Полезни съвети

URL ID

Анонимни действия

Коментарите не се връщат

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

Структура на шаблон за имейл

Забележки

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

GET /api/v1/email-templates

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

POST /api/v1/email-templates