API Data

L'API Data donne accès aux données publiques de votre site web, telles que les commentaires, les pages et les utilisateurs. Tous les points de terminaison utilisent la méthode HTTP GET et renvoient une réponse JSON.

Limitation du débit

L'API Data est conçue pour passer à l'échelle. Comme elle peut être utilisée dans le frontend pour récupérer le nombre de commentaires ou afficher une interface comme « commentaires les plus récents », elle est conçue pour s'adapter à votre trafic. Nous utilisons largement la mise en cache pour garantir que l'API est rapide et évolutive. Par conséquent, l' API Data n'impose aucune limite de débit au niveau du site web (il existe toutefois des limites liées à la sécurité). Vous pouvez l'utiliser en toute sécurité pour récupérer des données depuis vos frontends, même si votre site web a un trafic élevé.

Tarifs

Une requête à l'API Data qui n'est pas servie par le cache consomme un crédit API. La durée de mise en cache est actuellement de 30 secondes. Par exemple, si vous effectuez 1 000 appels en 30 secondes vers le même point de terminaison avec les mêmes données de requête, cela ne consommera qu'1 crédit API.

Côté serveur ou côté client

Il existe deux façons d'accéder à l'API.

Côté serveur : vous pouvez accéder à l'API Data depuis vos serveurs. L'accès est sécurisé par votre clé API. Vous trouverez votre clé de l'API Data dans la console. Dans la requête à l'API Data, ajoutez votre clé API comme paramètre de requête api_key avec les autres paramètres.

Côté client : vous pouvez accéder à l'API Data depuis votre frontend avec JavaScript. L'accès est sécurisé par l'en-tête HTTP Referer. Les domaines depuis lesquels vous accédez à l'API doivent être ajoutés aux domaines autorisés dans la console. Hyvor Talk rejettera les requêtes provenant d'autres domaines. Pour activer l'accès côté client, utilisez les paramètres d'accès public à l'API dans la console. Aucune clé API n'est nécessaire pour l'accès côté client.

Accéder à l'API

URL de base : https://talk.hyvor.com/api/data/v1

Tous les points de terminaison nécessitent le paramètre de requête website_id. Vous trouverez l'ID de votre site web dans la console.

Points de terminaison

Il existe 3 points de terminaison :

1. /comments - Renvoie un tableau d'objets Comment
2. /pages - Renvoie un tableau d'objets Page
3. /users - Renvoie un tableau d'objets User

Paramètres de requête

Tous les points de terminaison disposent des paramètres de requête suivants :

Définitions des objets

Toutes les dates sont au format timestamp UNIX (en secondes).

Commentaires

interface Comment {
	id: number;

	// pour les commentaires imbriqués
	// le premier id est le parent direct
	parent_ids: number[];
	depth: number;

	created_at: number;
	body_json: string; // ProseMirror JSON
	body_html: string;

	is_featured: boolean;
	is_loved: boolean;
	is_edited: boolean;

	upvotes: number;
	downvotes: number;

	user: User;
	page: Page;
}

Page

interface Page {
	id: number;
	created_at: number;
	identifier: string; // page-id
	url: string;
	title: string;
	comments_count: number;
	reactions: {
		superb: number;
		love: number;
		wow: number;
		sad: number;
		laugh: number;
		angry: number;
	};
	ratings: {
		average: number;
		count: number;
	};
}

Utilisateur

interface User {
	htid: string; // "hyvor_10" or "sso_10"
	name: string;
	title: string | null;
	username: string | null;
	picture_url: string | null;
	bio: string | null;
	location: string | null;
	website_url: string | null;
	created_at: number | null;
	last_commented_at: number | null;
	comments_count: number;
	badge_ids: number[];
}

Dans l'objet Comment, la clé user est un objet User. Pour les commentaires d'invités, l'objet user peut prendre la forme suivante :

// utilisateur invité
interface User {
	htid: null;
	name: string;
	picture_url: string | null;
}

Filtrage

Nous utilisons des expressions FilterQ pour permettre un filtrage avancé. Vous pouvez filtrer les commentaires, les pages et les utilisateurs avec le paramètre de requête filter.

Exemple de filter :

(created_at > '2022-01-01' & created_at < '2022-12-31') | is_featured=true

Une expression FilterQ se compose d'une ou plusieurs conditions. Une condition comporte trois parties :

• field
• operator
• value

Opérateur

• = - égal à
• != - différent de
• > - supérieur à
• < - inférieur à
• >= - supérieur ou égal à
• <= - inférieur ou égal à

Valeur

• null
• booléen : true ou false
• chaîne : 'hello' ou hello
• Les chaînes sans guillemets doivent correspondre à [a-zA-Z_][a-zA-Z0-9_-]+ et ne peuvent pas être true, false ou null.
• nombres : 250, -250, 2.5

Valeurs de date

Certaines clés acceptent des chaînes de date. Voici quelques valeurs de date valides :

• '2022-01-01'
• 'yesterday'
• 'first day of this year'
• 'last day of next month'
• '+1 day'
• '-1 week'
• 'next Thursday'
• 1639655890 (timestamp UNIX)

Par exemple : vous pouvez utiliser created_at>'-7 days' pour obtenir les données créées au cours des 7 derniers jours.

Opérateurs logiques

Vous pouvez utiliser des opérateurs logiques pour combiner plusieurs conditions.

• & - ET
• | - OU

Consultez la documentation sur les expressions FilterQ si vous avez besoin de plus de détails.

Clés prises en charge pour le filtrage

Tri

Définissez le paramètre de requête sort pour trier les résultats. Voici la liste des valeurs de tri prises en charge. Vous pouvez les combiner sous forme de valeurs séparées par des virgules, qui seront alors exécutées dans l'ordre, comme ORDER BY en SQL.

Exemples :

• created_at - Tri par date de création, par ordre décroissant
• created_at ASC - Tri par date de création, par ordre croissant
• is_featured DESC, created_at ASC - Tri par statut de mise en avant, par ordre décroissant, puis par date de création, par ordre croissant