Les API Steeple - Document général

Bienvenue sur les API Steeple

Pourquoi des API Steeple ?

Steeple offre plusieurs API REST destinées à améliorer l’intégration de Steeple dans un écosystème existant, exploiter ses ressources pour des usages dédiés ou encore favoriser la création de contenu depuis des systèmes tiers.

Les API Steeple sont, aujourd’hui, en pleine construction et de nouvelles fonctionnalités et opportunités seront dévoilées au fur et à mesure.

Prérequis

Pour exploiter les API Steeple, plusieurs prérequis sont nécessaires : 

• Avoir un compte actif sur Steeple : https://steeple.com/fr/ 
• Être membre d’une communauté associée à une organisation
• Avoir le rôle “Administrateur” sur cette communauté

API URL

Toutes les requêtes à destination des API Steeple doivent nécessairement commencer par : 

https://api.steeple.com 

Documentation technique

La documentation technique détaillée (type Swagger) est disponible ici : 

https://api-docs.steeple.com/ 

Authentification

Jeton d’authentification

Un jeton d’authentification est requis pour chaque requête envoyée. Le jeton d’authentification est une longue chaîne de caractères construite par Steeple qui peut ressembler à : 

Ce jeton d’authentification est utilisé pour savoir qui appelle les API et vérifier que seules les ressources permises peuvent être accédées.

Récupérer son jeton d’authentification

Rien de plus simple, pour cela, il faut se rendre sur Steeple. En tant qu’administrateur d’une communauté (cf. prérequis), il faut se rendre sur la page d’administration : 

 

Puis naviguer sur le menu “Intégrations” : 

Puis configurer les accès aux API Steeple : 

Générer un nouveau jeton d’authentification :

Renseigner les caractéristiques du jeton d’authentification : 

Votre jeton d’authentification est disponible.

Format d’authentification

Le jeton d’authentification est utilisé comme Bearer token et doit être présent dans tous les headers des requêtes envoyées aux API Steeple. 

Scope des données accessibles

Les données accessibles sont limitées au périmètre de l’organisation pour laquelle le jeton d’authentification a été généré.

Timezone

Toutes les dates sont exprimées au format ISO8601 basé sur l’UTC. Exemple : 

2023-03-22T13:08:55Z

Troubleshooting

Principes de base

Les API Steeple utilisent les codes d’erreurs HTTP standardisés. Chaque code d’erreur HTTP est accompagné d’une clé spécifiant la nature de l’erreur rencontrée pouvant varier d’une API à l’autre.

Erreurs d’authentification

Ci-dessous, les principaux cas d’erreurs liés à l’authentification :

Code HTTP	Erreur message	Cas d’erreur
401	Unauthorized	Le jeton d’authentification fourni ne permet pas de s’authentifier sur Steeple. Vérifier le jeton d’authentification. Si besoin, effectuer la génération d’un nouveau jeton d’authentification.
403	Forbidden	Le jeton d’authentification fourni permet de s’authentifier mais a été révoqué. La génération d’un nouveau jeton d’authentification est requise

Erreurs communes

Ci-dessous les principaux cas d’erreurs, se référer à la description des API pour obtenir des informations sur les erreurs spécifiques :

Code HTTP	Erreur message	Cas d’erreur
400	Bad Request	La requête est mal formée ou ne contient pas les informations requises pour opérer le traitement demandé. Vérifier les données transmises dans la requête. Contacter le support au besoin.
404	Not Found	La requête fait référence à une ressource introuvable. Vérifier les données transmises dans la requête. Contacter le support au besoin.
422	Unprocessable entity	La requête fournit des informations incomplètes ou incompréhensibles. Vérifier les données transmises dans la requête.
500	Internal Server Error	Le serveur ne permet pas de traiter la requête. Rejouer la requête plus tard, si le problème persiste, contacter le support.

 

Glossaire

Organisation  (Organization)

L’organisation représente votre contexte dans Steeple. Tout ce qui est dans cette organisation vous est accessible. Il vous est, en revanche, impossible d’accéder à des ressources appartenant à une autre organisation. Une organisation est composée d’au moins une communauté. Si, dans la plupart des cas, une organisation ne possède qu’une communauté, certains contextes clients nécessitent de nombreuses communautés. Les ressources de toutes les communautés associées à cette organisation sont donc accessibles pour quelqu’un de cette organisation.

Communauté  (Community)

La communauté est un ensemble d’utilisateurs (membres) regroupés et partageant de nombreuses informations (publications, évènements, modules, etc.). Une communauté peut être associée directement à une organisation, ou, dans le cadre d’une communauté fille, à une autre communauté.

Catégories et Sous-Catégories (Groups)

Les catégories et sous-catégories sont utilisées dans les communautés pour ranger, organiser les publications. Il y a toujours au moins une catégorie dans une communauté et il y a toujours au moins une sous-catégorie à une catégorie. Les sous-catégories sont explicitement utilisées pour ranger les publications lors de leur création.

Utilisateur (User)

Un utilisateur Steeple est une personne physique qui possède un compte actif sur Steeple et qui est membre d’une communauté et donc d’une organisation. Un utilisateur peut interagir avec de nombreuses ressources dans Steeple (Publications, commentaires, sondages, etc.) mais seuls les utilisateurs avec un profil “Administrateur” peuvent gérer des communautés. Ce sont également ces profils administrateurs qui peuvent gérer les jetons d’authentification.

Jeton d’authentification (Access Token)

Le jeton d’authentification permet à un système souhaitant requêter les API Steeple de s’authentifier. Le jeton d’authentification est généré par Steeple et vérifié à chaque requête reçue. La vérification permet également de valider les ressources accessibles ou non.

Publication (Post)

Une publication est un contenu partagé à une ou plusieurs communautés. Elle est composée d’un titre, d’une description et de médias. Elle est nominative, c'est-à-dire qu’elle est nécessairement associée à un auteur, à savoir, un utilisateur de la communauté. Une publication est obligatoirement associée à une catégorie.

Média (Media)

Les médias accompagnent les publications afin d’enrichir le contenu partagé. Il peut s’agir d’images, de vidéos ou encore de fichiers PDF.