API REST

L’API REST fait de votre bibliothèque freedam non plus un lieu que l’on visite, mais un élément auquel vos autres systèmes peuvent se brancher. Votre site web peut récupérer les visuels produit directement à la source de référence, vos outils de production peuvent déposer automatiquement les fichiers terminés, et quand une image est retouchée, elle est mise à jour partout en même temps, car tout pointe vers le même média.

Ce qu’elle fait

L’API couvre toute la bibliothèque, et ses adresses restent stables : les intégrations que vous construisez aujourd’hui continuent donc de fonctionner :

• Médias – lister, récupérer, modifier et supprimer des médias. Chaque média a un ID public permanent : les liens qui y mènent ne cassent jamais.
• Collections – créer et gérer des collections, y ajouter et en retirer des médias.
• Imports – envoyer des fichiers par lots et suivre leur avancement jusqu’à leur traitement complet.
• Métadonnées – lire vos définitions de champs et vos termes de vocabulaire validés, pour que vos propres outils proposent des valeurs valides sans les coder en dur.
• Partages – créer, modifier et révoquer des liens de partage, avec mots de passe, dates d’expiration et permissions de téléchargement.
• Opérations – lancer de gros traitements (modifications en masse, suppressions en masse, analyse IA, exports) et les laisser s’exécuter en arrière-plan.
• Webhooks – faire notifier vos systèmes par freedam quand quelque chose se produit, au lieu que vos systèmes interrogent sans cesse.
• Vidéos intégrées – générer des codes d’intégration pour les médias vidéo.
• Consentements et tokens – consulter l’acceptation des conditions d’utilisation et gérer l’accès à l’API par programmation.

L’API publie aussi une description d’elle-même lisible par machine (une spécification OpenAPI). C’est à partir d’elle qu’est construit le SDK TypeScript officiel, et les développeurs peuvent s’en servir pour générer un client prêt à l’emploi dans presque tous les langages de programmation.

Comment ça marche

L’accès est contrôlé par des tokens. Vous en créez un dans Paramètres → Tokens API et vous choisissez exactement ce qu’il a le droit de faire – par exemple lire les médias mais jamais les supprimer. Le logiciel qui détient ce token peut faire ces actions, et rien de plus :

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://your-instance.example.com/api/v1/assets

On ne peut jamais donner à un token plus de pouvoir qu’en a la personne qui l’a créé. Et quand une requête est refusée, la réponse indique précisément quelle permission manquait : corriger le problème est une simple consultation, pas une devinette.

Chaque requête API est aussi consignée dans un journal d’audit – qui a appelé, avec quel token, pour faire quoi et depuis où. Chaque token indique quand et d’où il a été utilisé pour la dernière fois : un appelant inattendu se repère et se révoque facilement.

À savoir

• Des limites de débit raisonnables s’appliquent : chaque token peut faire 60 requêtes par minute, et les réponses indiquent aux appelants quand ralentir. Pour les gros traitements, utilisez les opérations – une seule requête quel que soit le nombre de médias concernés – et les webhooks plutôt que des vérifications répétées.
• Les tokens ne s’affichent qu’une fois à leur création ; freedam ne stocke jamais le token lui-même. La révocation d’un token est immédiate.
• La livraison d’images est distincte : des URL d’image rapides et sans cookie pour votre site web ont leur propre section dans la documentation de l’API.
• Les instances auto-hébergées ont la même API aux mêmes adresses : vos intégrations vous suivent.

Le catalogue complet des endpoints et la documentation de référence se trouvent dans la documentation de l’API. Si vous envisagez un déploiement auto-hébergé et souhaitez en discuter, contactez-nous.