Le dépôt de plugins et de thèmes de dotclear.org ne se limite pas à ses pages web : il répond aussi à une API. Elle permet à un programme de parcourir le dépôt, de savoir si un module a une version plus récente, de suivre ses propres contributions et d'en envoyer une nouvelle version, sans passer par le formulaire de contribution.
Ce billet s'adresse aux auteurs de plugins et de thèmes qui veulent automatiser leurs publications (depuis un workflow GitHub, un script maison…) ou écrire leur propre client.
Les principes
- Adresse : tous les points d'entrée sont sous
https://dotclear.org/api/, par exemplehttps://dotclear.org/api/auth. En repli, le dépôt de test et de secourshttps://repo.dotclear.watch/api/répond à la même API. - Tout se fait en POST, avec des champs de formulaire classiques (
application/x-www-form-urlencodedoumultipart/form-data). - Un champ envoyé ne doit jamais être vide : un champ facultatif que vous n'utilisez pas doit être absent de la requête, sinon l'API répond par le code 104 (paramètre manquant). Attention, la valeur
0compte aussi comme vide :offset=0oucount=0sont refusés, il faut retirer le champ. C'est le piège le plus courant. - Connexion par jeton : on demande un jeton avec son identifiant et son mot de passe, puis on l'envoie dans l'en-tête
Authorization: Bearer …de chaque appel. Tous les points d'entrée demandent un jeton, saufauth(qui le délivre) etblog. - Version de l'API : l'en-tête
X-API-Version: v1est facultatif (v1par défaut), mais l'envoyer protège votre client d'une future version. - Limite d'appels : chaque compte a un crédit d'appels par période (3600 par heure par défaut, réglable compte par compte par les administrateurs du dépôt). Chaque appel en consomme de 1 à 10 selon le point d'entrée, le plus coûteux étant l'envoi d'une contribution ;
authetendpointssont gratuits. Les réponses réussies donnent l'état du quota dans leurs en-têtesX-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset(date de remise à zéro, au format ISO 8601) etX-RateLimit-NearLimit(qui vaut 1 quand la limite approche) ; les réponses d'erreur ne les donnent pas. Au-delà de la limite, l'API répond 429, avec un en-têteRetry-After(en secondes), jusqu'à la remise à zéro. - Le type de module : la plupart des points d'entrée travaillent sur un seul type à la fois, donné par le champ obligatoire
type, qui vautpluginoutheme.
Le compte
Il faut un compte de contributeur sur le dépôt, celui-là même qui sert au formulaire de contribution du site. Avec ce compte, l'API permet de consulter le dépôt et de mettre à jour ses propres modules.
Déposer un nouveau module par l'API demande un droit en plus, accordé à la main par l'équipe Dotclear aux contributeurs qui en ont l'usage. Sans ce droit, un nouveau module passe toujours par le formulaire du site. Avec ce droit, un nouveau module envoyé par l'API doit donner sa catégorie et attend toujours la relecture des administrateurs avant d'être en ligne. Le point d'entrée user (voir plus bas) indique si votre compte a ce droit.
Le format des réponses
Toutes les réponses sont en JSON et ont la même forme :
{
"code": 200,
"message": "",
"content": { … },
"cache": "0"
}
code est le code de l'API, message un texte éventuel (en cas d'erreur, ou pour confirmer un envoi), content les données, et cache vaut 1 quand la réponse vient du cache du serveur. Le statut HTTP suit le code de l'API, mais c'est le champ code qui est le plus précis :
| Code | Sens | HTTP |
|---|---|---|
| 200 | Ok | 200 |
| 101 | Service fermé (API ou type de module désactivé) | 503 |
| 102 | Point d'entrée inconnu, ou type de module invalide | 405 |
| 103 | Version de l'API non supportée | 400 |
| 104 | Paramètre manquant (ou envoyé vide) | 400 |
| 105 | Pas de contenu | 404 |
| 106 | Non trouvé | 404 |
| 107 | Contributions fermées pour le moment | 503 |
| 108 | Échec de la soumission (la raison est dans message) |
422 |
| 109 | Non autorisé (mauvais identifiants, jeton invalide ou expiré, droit manquant) | 401 |
| 429 | Limite d'appels atteinte | 429 |
| 100 | Erreur inconnue | 500 |
Obtenir un jeton : auth
curl -X POST https://dotclear.org/api/auth \
-d "username=mon-identifiant" \
-d "password=mon-mot-de-passe"
La réponse donne le jeton, sa date d'expiration et l'état du quota (les dates sont au format ISO 8601, en UTC) :
{
"code": 200,
"message": "",
"content": {
"name": "Claire Martin",
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOi…",
"token_reset": "2026-11-17T21:39:00+00:00",
"rate_limit": 3600,
"rate_remain": 3600,
"rate_reset": "2026-11-17T21:39:00+00:00"
},
"cache": "0"
}
Le jeton a une durée de vie limitée, fixée par le dépôt (une heure par défaut). Gardez-le et réutilisez-le pour tous les appels suivants plutôt que d'en redemander un à chaque requête ; redemandez-en un juste avant token_reset, ou quand l'API répond 109.
curl -X POST https://dotclear.org/api/user \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi…" \
-H "X-API-Version: v1"
Les points d'entrée
Généraux
user: votre nom, votre jeton et votre quota, plus quelques chiffres sur votre compte :pluginsetthemes(nombre de vos modules publiés),pending(vos envois en attente de relecture) etcan_add_module(1 si votre compte peut déposer un nouveau module par l'API, 0 sinon). Un client ne devrait proposer le dépôt d'un nouveau module que sican_add_modulevaut 1.endpoints: la liste des points d'entrée et des champs qu'ils attendent (obligatoires ou non). C'est la référence à consulter si un client doit s'adapter au serveur.codes: la liste des codes de réponse et de leurs textes, ou le texte d'un seul code avec le champcode.blog: les informations publiques du site (nom, adresse, description, date de mise à jour), sans jeton.
Listes de référence
Elles servent à remplir des listes de choix dans un client, ou à vérifier une valeur avant un envoi :
categories(champtype) : les catégories du dépôt, sous la forme identifiant ⇒ titre ;tags(champtype) : les mots-clés utilisables ;licenses: les licences reconnues, sous la forme code ⇒ libellé (par exemplegpl2,agpl3,mit) ;dcmin: les versions de Dotclear connues du dépôt ;warnings: les avertissements qui peuvent être posés sur un module (obsolète, bogué…) ;statuses: les états possibles d'une version de module.
Consulter le dépôt
list: chercher des modules. Champs :type(obligatoire), puis au choixq(recherche),category(identifiant de catégorie),tag,dc_min(ne garder que les modules compatibles avec cette version de Dotclear),limit(10 par défaut, 100 au plus),offset,sortby(nameoudate),order(ascoudesc), etcountpour n'obtenir que le nombre de résultats. Chaque version publiée d'un module est un résultat à part, d'où l'indexidentifiant-version; le champlastvaut 1 pour la version courante du module.detail: la fiche complète d'un module. Champs :type,module(son identifiant), etversionpour une version précise, y compris une version plus ancienne que la version courante (sinon la version courante).last: la plus haute version de chaque module, indexée par identifiant. Champs :type,modules(liste d'identifiants séparés par des virgules) etdc_min. C'est le point d'entrée idéal pour vérifier les mises à jour des modules installés sur un blog.
Exemple : les dernières versions de deux plugins compatibles avec Dotclear 2.40 :
curl -X POST https://dotclear.org/api/last \
-H "Authorization: Bearer $TOKEN" \
-d "type=plugin" \
-d "modules=ApiServer,periodical" \
-d "dc_min=2.40"
Chaque module renvoie au moins id, name, version, desc, author, date, dc_min, file (adresse du paquet zip), detail et support ; list et last y ajoutent la catégorie, les mots-clés, un éventuel avertissement, last (1 pour la version courante) et des versions numériques faciles à comparer (version_num, dc_min_num) ; detail donne tout cela, plus l'état, le nombre de téléchargements, la documentation, sa syntaxe, l'icône, la licence et les libellés de ces valeurs. Les thèmes ont aussi leur capture d'écran (screenshot).
Suivre ses contributions : mine
Champs : type, et au choix module (un seul module) et limit. Pour chacun de vos modules, l'API renvoie la version courante, ou la version en attente de relecture s'il y en a une, avec son état et son nombre de téléchargements.
Envoyer une version : update
C'est le point d'entrée qui remplace le formulaire de contribution. Il sert à mettre à jour un de vos modules, à déposer une version plus ancienne que sa version courante, ou à déposer un nouveau module si votre compte en a le droit. Le paquet zip est envoyé encodé en base64 dans un champ texte, pas comme un fichier joint.
| Champ | Rôle |
|---|---|
type |
Obligatoire : plugin ou theme. |
zip |
Obligatoire : le paquet zip du module, en base64. |
category |
Identifiant de catégorie (voir categories). Obligatoire pour un nouveau module, facultatif pour une mise à jour (la catégorie de la version courante est alors reprise). |
tags |
Mots-clés séparés par des virgules (voir tags). Les mots-clés inconnus du dépôt sont ignorés. |
license |
Code de licence (voir licenses). |
readme_update |
Mettre à 1 pour reprendre le README.md du paquet comme documentation de la fiche. |
screenshot, screenshot_ext |
Une capture en base64 et son extension (png, jpg…), ou un zip de plusieurs images. Surtout utile aux thèmes. |
L'identifiant, le nom et la version du module sont lus dans le _define.php du paquet : il doit être propre et suivre le modèle habituel, avec une version de 1 à 3 nombres (2.5, 1.0.3, 2026.11.17), sans lettre ni suffixe.
Pour une mise à jour, les champs facultatifs que vous n'envoyez pas (catégorie, mots-clés, licence…) sont repris de la version courante du module, de même que les informations absentes du _define.php (version de Dotclear requise, lien de support…).
Les règles d'une contribution
- Une version n'existe qu'une fois par module, quel que soit son état : une version déjà publiée, en attente de relecture ou retirée du dépôt ne peut pas être envoyée de nouveau. Pour corriger une version publiée, il faut publier une nouvelle version.
- Une seule contribution en attente par module : tant qu'une version attend la relecture des administrateurs, le module ne peut pas recevoir d'autre envoi.
- Un nouveau module demande le droit correspondant et une catégorie, et passe toujours par la relecture, même si votre compte voit ses mises à jour publiées directement.
Déposer une version plus ancienne
Il est possible d'envoyer une version plus ancienne que la version courante d'un module, par exemple un correctif pour la branche d'un plugin qui fonctionne encore avec une version précédente de Dotclear. La version courante reste toujours la plus haute version publiée, quel que soit l'ordre des envois ou des validations : la version plus ancienne s'ajoute à l'historique du module sans le remplacer.
Deux différences avec une mise à jour classique :
- La version de Dotclear requise est obligatoire dans le
_define.phpdu paquet (requiressurcore). Elle n'est jamais reprise de la version courante, qui demande souvent un Dotclear plus récent : la version plus ancienne serait alors invisible pour les installations qu'elle vise. - La documentation n'est pas reprise de la version courante, qui ne décrit pas forcément l'ancienne : envoyez
readme_update=1avec unREADME.mddans le paquet.
Les autres informations (catégorie, mots-clés, licence, lien de support…) sont reprises comme pour une mise à jour.
La réponse
En cas de succès, la réponse rappelle le module reçu, et message dit s'il est déjà en ligne ou s'il attend la relecture des administrateurs (c'est toujours le cas pour un nouveau module) :
{
"code": 200,
"message": "Thank you for your submission! Your contribution is valid and online.",
"content": {
"type": "plugin",
"id": "monPlugin",
"name": "Mon plugin",
"version": "1.2"
},
"cache": "0"
}
En cas de refus, le code 108 est accompagné de la raison dans message : paquet invalide, version qui existe déjà, autre version du module encore en attente de relecture, nouveau module sans le droit ou sans catégorie, version plus ancienne sans version de Dotclear requise… Affichez ce message tel quel : c'est le serveur qui décide, un client n'a pas à refaire ses contrôles.
Un exemple complet en PHP
Le script suivant demande un jeton, puis envoie le zip d'un plugin. C'est, en plus simple, ce que font les workflows de publication de mes plugins sur GitHub.
<?php
$api = 'https://dotclear.org/api/'; // repli : https://repo.dotclear.watch/api/
$login = getenv('DA_USERNAME');
$pass = getenv('DA_PASSWORD');
$zip = 'plugin-monPlugin.zip';
$category = ''; // identifiant de catégorie, obligatoire pour un nouveau module
$call = function (string $endpoint, array $fields, string $token = '') use ($api): array {
$ch = curl_init($api . $endpoint);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => array_filter($fields, fn ($v) => $v !== ''), // jamais de champ vide
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false, // ne pas renvoyer le jeton vers un autre hôte
CURLOPT_HTTPHEADER => array_filter([
'X-API-Version: v1',
$token !== '' ? 'Authorization: Bearer ' . $token : '',
]),
]);
$rsp = json_decode((string) curl_exec($ch), true);
curl_close($ch);
return is_array($rsp) ? $rsp : ['code' => 100, 'message' => 'Réponse illisible'];
};
// 1. Jeton
$rsp = $call('auth', ['username' => $login, 'password' => $pass]);
if ($rsp['code'] !== 200) {
exit('Connexion refusée : ' . $rsp['message'] . "\n");
}
$token = $rsp['content']['token'];
// 2. Envoi de la version (mise à jour, version plus ancienne ou nouveau module)
$rsp = $call('update', [
'type' => 'plugin',
'zip' => chunk_split(base64_encode((string) file_get_contents($zip))),
'category' => $category, // retiré par array_filter() s'il est vide
'readme_update' => '1',
'license' => 'gpl2',
], $token);
echo $rsp['code'] . ' : ' . $rsp['message'] . "\n";
Bonnes pratiques pour un client
- Toujours en https : identifiant, mot de passe et jeton passent dans les requêtes.
- Ne pas suivre les redirections : la plupart des bibliothèques HTTP renverraient l'en-tête
Authorizationà l'adresse de destination. Une redirection est une erreur de configuration à corriger. - Vérifier que c'est bien l'API qui répond : une mauvaise adresse peut répondre 200 avec une page HTML. La présence de l'en-tête
X-RateLimit-Remainingsur une réponse réussie est un bon test. - Ménager le quota : réutiliser le jeton, garder en mémoire les réponses identiques (les listes de référence changent rarement), et ralentir quand
X-RateLimit-NearLimitvaut 1. - Échapper tout ce qui vient de l'API avant de l'afficher : noms, descriptions et documentations sont écrits par les contributeurs.
- Ne garder que les champs utiles : la liste des champs renvoyés peut s'enrichir ; un client doit ignorer ceux qu'il ne connaît pas.
Pour aller plus loin
Le moteur de l'API est le plugin ApiServer, dont le guide d'utilisation détaille les jetons, les quotas et les codes de réponse. Pour tester l'API sans écrire une ligne de code, le plugin daContribute fait l'objet d'un billet à part : il sert de client complet dans l'administration de votre blog, avec un explorateur des points d'entrée.