<?xml version="1.0" encoding="utf-8"?><rss xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:noNamespaceSchemaLocation="rss2.xsd" version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:wfw="http://wellformedweb.org/CommentAPI/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>DotclearWatch / Blog - Mot-clé - api</title>
    <link>https://dotclear.watch/</link>
    <atom:link href="http://dotclear.watch/feed/tag/api/rss2" rel="self" type="application/rss+xml" />
    <description>Suivez l'évolution du moteur de blogs Dotclear.</description>
    <language>fr</language>
    <pubDate>Sat, 21 Nov 2026 11:34:29 +0100</pubDate>
    <copyright>Tous droits réservés © Jean-Christian Denis</copyright>
    <docs>http://blogs.law.harvard.edu/tech/rss</docs>
    <generator>Dotclear</generator>
          <item>
        <title>Utiliser l'API du dépôt de modules Dotclear</title>
        <link>https://dotclear.watch/Billet/Utiliser-l-API-du-d%C3%A9p%C3%B4t-de-modules-Dotclear</link>
        <guid isPermaLink="false">urn:md5:ef14f90fdb85d1663ac6c68d547a033d</guid>
        <pubDate>Tue, 17 Nov 2026 21:39:00 +0100</pubDate>
        <dc:creator>Jean-Christian Denis</dc:creator>
                  <category>Articles</category>
                          <category>api</category>
                  <category>depot</category>
                  <category>jeton</category>
                  <category>module</category>
                  <category>plugin</category>
                  <category>repository</category>
                  <category>theme</category>
                <description>&lt;p&gt;Le dépôt officiel des plugins et thèmes Dotclear propose une API : chercher des modules, vérifier les mises à jour, suivre ses contributions et envoyer une nouvelle version sans passer par le formulaire web. Mode d'emploi complet, exemples à l'appui.&lt;/p&gt; &lt;p&gt;Le dépôt de plugins et de thèmes de &lt;a href=&quot;https://dotclear.org/&quot; hreflang=&quot;fr&quot;&gt;dotclear.org&lt;/a&gt; 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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h3&gt;Les principes&lt;/h3&gt;

&lt;ul&gt;
	&lt;li&gt;&lt;strong&gt;Adresse&lt;/strong&gt; : tous les points d'entrée sont sous &lt;code&gt;https://dotclear.org/api/&lt;/code&gt;, par exemple &lt;code&gt;https://dotclear.org/api/auth&lt;/code&gt;. En repli, le dépôt de test et de secours &lt;code&gt;https://repo.dotclear.watch/api/&lt;/code&gt; répond à la même API.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Tout se fait en POST&lt;/strong&gt;, avec des champs de formulaire classiques (&lt;code&gt;application/x-www-form-urlencoded&lt;/code&gt; ou &lt;code&gt;multipart/form-data&lt;/code&gt;).&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Un champ envoyé ne doit jamais être vide&lt;/strong&gt; : 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 &lt;code&gt;0&lt;/code&gt; compte aussi comme vide : &lt;code&gt;offset=0&lt;/code&gt; ou &lt;code&gt;count=0&lt;/code&gt; sont refusés, il faut retirer le champ. C'est le piège le plus courant.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Connexion par jeton&lt;/strong&gt; : on demande un jeton avec son identifiant et son mot de passe, puis on l'envoie dans l'en-tête &lt;code&gt;Authorization: Bearer …&lt;/code&gt; de chaque appel. Tous les points d'entrée demandent un jeton, sauf &lt;code&gt;auth&lt;/code&gt; (qui le délivre) et &lt;code&gt;blog&lt;/code&gt;.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Version de l'API&lt;/strong&gt; : l'en-tête &lt;code&gt;X-API-Version: v1&lt;/code&gt; est facultatif (&lt;code&gt;v1&lt;/code&gt; par défaut), mais l'envoyer protège votre client d'une future version.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Limite d'appels&lt;/strong&gt; : 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 ; &lt;code&gt;auth&lt;/code&gt; et &lt;code&gt;endpoints&lt;/code&gt; sont gratuits. Les réponses réussies donnent l'état du quota dans leurs en-têtes &lt;code&gt;X-RateLimit-Limit&lt;/code&gt;, &lt;code&gt;X-RateLimit-Remaining&lt;/code&gt;, &lt;code&gt;X-RateLimit-Reset&lt;/code&gt; (date de remise à zéro, au format ISO 8601) et &lt;code&gt;X-RateLimit-NearLimit&lt;/code&gt; (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ête &lt;code&gt;Retry-After&lt;/code&gt; (en secondes), jusqu'à la remise à zéro.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Le type de module&lt;/strong&gt; : la plupart des points d'entrée travaillent sur un seul type à la fois, donné par le champ obligatoire &lt;code&gt;type&lt;/code&gt;, qui vaut &lt;code&gt;plugin&lt;/code&gt; ou &lt;code&gt;theme&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;Le compte&lt;/h3&gt;

&lt;p&gt;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 &lt;strong&gt;ses propres modules&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;Déposer un &lt;strong&gt;nouveau module&lt;/strong&gt; 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 &lt;code&gt;user&lt;/code&gt; (voir plus bas) indique si votre compte a ce droit.&lt;/p&gt;

&lt;h3&gt;Le format des réponses&lt;/h3&gt;

&lt;p&gt;Toutes les réponses sont en JSON et ont la même forme :&lt;/p&gt;

&lt;pre&gt;
&lt;code class=&quot;language-json&quot;&gt;{
  &quot;code&quot;: 200,
  &quot;message&quot;: &quot;&quot;,
  &quot;content&quot;: { … },
  &quot;cache&quot;: &quot;0&quot;
}&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;&lt;code&gt;code&lt;/code&gt; est le code de l'API, &lt;code&gt;message&lt;/code&gt; un texte éventuel (en cas d'erreur, ou pour confirmer un envoi), &lt;code&gt;content&lt;/code&gt; les données, et &lt;code&gt;cache&lt;/code&gt; 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 &lt;code&gt;code&lt;/code&gt; qui est le plus précis :&lt;/p&gt;

&lt;table&gt;
	&lt;thead&gt;
		&lt;tr&gt;
			&lt;th&gt;Code&lt;/th&gt;
			&lt;th&gt;Sens&lt;/th&gt;
			&lt;th&gt;HTTP&lt;/th&gt;
		&lt;/tr&gt;
	&lt;/thead&gt;
	&lt;tbody&gt;
		&lt;tr&gt;
			&lt;td&gt;200&lt;/td&gt;
			&lt;td&gt;Ok&lt;/td&gt;
			&lt;td&gt;200&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;101&lt;/td&gt;
			&lt;td&gt;Service fermé (API ou type de module désactivé)&lt;/td&gt;
			&lt;td&gt;503&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;102&lt;/td&gt;
			&lt;td&gt;Point d'entrée inconnu, ou type de module invalide&lt;/td&gt;
			&lt;td&gt;405&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;103&lt;/td&gt;
			&lt;td&gt;Version de l'API non supportée&lt;/td&gt;
			&lt;td&gt;400&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;104&lt;/td&gt;
			&lt;td&gt;Paramètre manquant (ou envoyé vide)&lt;/td&gt;
			&lt;td&gt;400&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;105&lt;/td&gt;
			&lt;td&gt;Pas de contenu&lt;/td&gt;
			&lt;td&gt;404&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;106&lt;/td&gt;
			&lt;td&gt;Non trouvé&lt;/td&gt;
			&lt;td&gt;404&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;107&lt;/td&gt;
			&lt;td&gt;Contributions fermées pour le moment&lt;/td&gt;
			&lt;td&gt;503&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;108&lt;/td&gt;
			&lt;td&gt;Échec de la soumission (la raison est dans &lt;code&gt;message&lt;/code&gt;)&lt;/td&gt;
			&lt;td&gt;422&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;109&lt;/td&gt;
			&lt;td&gt;Non autorisé (mauvais identifiants, jeton invalide ou expiré, droit manquant)&lt;/td&gt;
			&lt;td&gt;401&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;429&lt;/td&gt;
			&lt;td&gt;Limite d'appels atteinte&lt;/td&gt;
			&lt;td&gt;429&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;100&lt;/td&gt;
			&lt;td&gt;Erreur inconnue&lt;/td&gt;
			&lt;td&gt;500&lt;/td&gt;
		&lt;/tr&gt;
	&lt;/tbody&gt;
&lt;/table&gt;

&lt;h3&gt;Obtenir un jeton : &lt;code&gt;auth&lt;/code&gt;&lt;/h3&gt;

&lt;pre&gt;
&lt;code class=&quot;language-bash&quot;&gt;curl -X POST https://dotclear.org/api/auth \
  -d &quot;username=mon-identifiant&quot; \
  -d &quot;password=mon-mot-de-passe&quot;&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;La réponse donne le jeton, sa date d'expiration et l'état du quota (les dates sont au format ISO 8601, en UTC) :&lt;/p&gt;

&lt;pre&gt;
&lt;code class=&quot;language-json&quot;&gt;{
  &quot;code&quot;: 200,
  &quot;message&quot;: &quot;&quot;,
  &quot;content&quot;: {
    &quot;name&quot;: &quot;Claire Martin&quot;,
    &quot;token&quot;: &quot;eyJ0eXAiOiJKV1QiLCJhbGciOi…&quot;,
    &quot;token_reset&quot;: &quot;2026-11-17T21:39:00+00:00&quot;,
    &quot;rate_limit&quot;: 3600,
    &quot;rate_remain&quot;: 3600,
    &quot;rate_reset&quot;: &quot;2026-11-17T21:39:00+00:00&quot;
  },
  &quot;cache&quot;: &quot;0&quot;
}&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;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 &lt;code&gt;token_reset&lt;/code&gt;, ou quand l'API répond 109.&lt;/p&gt;

&lt;pre&gt;
&lt;code class=&quot;language-bash&quot;&gt;curl -X POST https://dotclear.org/api/user \
  -H &quot;Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi…&quot; \
  -H &quot;X-API-Version: v1&quot;&lt;/code&gt;&lt;/pre&gt;

&lt;h3&gt;Les points d'entrée&lt;/h3&gt;

&lt;h4&gt;Généraux&lt;/h4&gt;

&lt;ul&gt;
	&lt;li&gt;&lt;code&gt;user&lt;/code&gt; : votre nom, votre jeton et votre quota, plus quelques chiffres sur votre compte : &lt;code&gt;plugins&lt;/code&gt; et &lt;code&gt;themes&lt;/code&gt; (nombre de vos modules publiés), &lt;code&gt;pending&lt;/code&gt; (vos envois en attente de relecture) et &lt;code&gt;can_add_module&lt;/code&gt; (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 si &lt;code&gt;can_add_module&lt;/code&gt; vaut 1.&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;endpoints&lt;/code&gt; : 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.&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;codes&lt;/code&gt; : la liste des codes de réponse et de leurs textes, ou le texte d'un seul code avec le champ &lt;code&gt;code&lt;/code&gt;.&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;blog&lt;/code&gt; : les informations publiques du site (nom, adresse, description, date de mise à jour), sans jeton.&lt;/li&gt;
&lt;/ul&gt;

&lt;h4&gt;Listes de référence&lt;/h4&gt;

&lt;p&gt;Elles servent à remplir des listes de choix dans un client, ou à vérifier une valeur avant un envoi :&lt;/p&gt;

&lt;ul&gt;
	&lt;li&gt;&lt;code&gt;categories&lt;/code&gt; (champ &lt;code&gt;type&lt;/code&gt;) : les catégories du dépôt, sous la forme identifiant ⇒ titre ;&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;tags&lt;/code&gt; (champ &lt;code&gt;type&lt;/code&gt;) : les mots-clés utilisables ;&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;licenses&lt;/code&gt; : les licences reconnues, sous la forme code ⇒ libellé (par exemple &lt;code&gt;gpl2&lt;/code&gt;, &lt;code&gt;agpl3&lt;/code&gt;, &lt;code&gt;mit&lt;/code&gt;) ;&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;dcmin&lt;/code&gt; : les versions de Dotclear connues du dépôt ;&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;warnings&lt;/code&gt; : les avertissements qui peuvent être posés sur un module (obsolète, bogué…) ;&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;statuses&lt;/code&gt; : les états possibles d'une version de module.&lt;/li&gt;
&lt;/ul&gt;

&lt;h4&gt;Consulter le dépôt&lt;/h4&gt;

&lt;ul&gt;
	&lt;li&gt;&lt;code&gt;list&lt;/code&gt; : chercher des modules. Champs : &lt;code&gt;type&lt;/code&gt; (obligatoire), puis au choix &lt;code&gt;q&lt;/code&gt; (recherche), &lt;code&gt;category&lt;/code&gt; (identifiant de catégorie), &lt;code&gt;tag&lt;/code&gt;, &lt;code&gt;dc_min&lt;/code&gt; (ne garder que les modules compatibles avec cette version de Dotclear), &lt;code&gt;limit&lt;/code&gt; (10 par défaut, 100 au plus), &lt;code&gt;offset&lt;/code&gt;, &lt;code&gt;sortby&lt;/code&gt; (&lt;code&gt;name&lt;/code&gt; ou &lt;code&gt;date&lt;/code&gt;), &lt;code&gt;order&lt;/code&gt; (&lt;code&gt;asc&lt;/code&gt; ou &lt;code&gt;desc&lt;/code&gt;), et &lt;code&gt;count&lt;/code&gt; pour n'obtenir que le nombre de résultats. Chaque version publiée d'un module est un résultat à part, d'où l'index &lt;code&gt;identifiant-version&lt;/code&gt; ; le champ &lt;code&gt;last&lt;/code&gt; vaut 1 pour la version courante du module.&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;detail&lt;/code&gt; : la fiche complète d'un module. Champs : &lt;code&gt;type&lt;/code&gt;, &lt;code&gt;module&lt;/code&gt; (son identifiant), et &lt;code&gt;version&lt;/code&gt; pour une version précise, y compris une version plus ancienne que la version courante (sinon la version courante).&lt;/li&gt;
	&lt;li&gt;&lt;code&gt;last&lt;/code&gt; : la plus haute version de chaque module, indexée par identifiant. Champs : &lt;code&gt;type&lt;/code&gt;, &lt;code&gt;modules&lt;/code&gt; (liste d'identifiants séparés par des virgules) et &lt;code&gt;dc_min&lt;/code&gt;. C'est le point d'entrée idéal pour &lt;strong&gt;vérifier les mises à jour&lt;/strong&gt; des modules installés sur un blog.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Exemple : les dernières versions de deux plugins compatibles avec Dotclear 2.40 :&lt;/p&gt;

&lt;pre&gt;
&lt;code class=&quot;language-bash&quot;&gt;curl -X POST https://dotclear.org/api/last \
  -H &quot;Authorization: Bearer $TOKEN&quot; \
  -d &quot;type=plugin&quot; \
  -d &quot;modules=ApiServer,periodical&quot; \
  -d &quot;dc_min=2.40&quot;&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;Chaque module renvoie au moins &lt;code&gt;id&lt;/code&gt;, &lt;code&gt;name&lt;/code&gt;, &lt;code&gt;version&lt;/code&gt;, &lt;code&gt;desc&lt;/code&gt;, &lt;code&gt;author&lt;/code&gt;, &lt;code&gt;date&lt;/code&gt;, &lt;code&gt;dc_min&lt;/code&gt;, &lt;code&gt;file&lt;/code&gt; (adresse du paquet zip), &lt;code&gt;detail&lt;/code&gt; et &lt;code&gt;support&lt;/code&gt; ; &lt;code&gt;list&lt;/code&gt; et &lt;code&gt;last&lt;/code&gt; y ajoutent la catégorie, les mots-clés, un éventuel avertissement, &lt;code&gt;last&lt;/code&gt; (1 pour la version courante) et des versions numériques faciles à comparer (&lt;code&gt;version_num&lt;/code&gt;, &lt;code&gt;dc_min_num&lt;/code&gt;) ; &lt;code&gt;detail&lt;/code&gt; 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 (&lt;code&gt;screenshot&lt;/code&gt;).&lt;/p&gt;

&lt;h4&gt;Suivre ses contributions : &lt;code&gt;mine&lt;/code&gt;&lt;/h4&gt;

&lt;p&gt;Champs : &lt;code&gt;type&lt;/code&gt;, et au choix &lt;code&gt;module&lt;/code&gt; (un seul module) et &lt;code&gt;limit&lt;/code&gt;. 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.&lt;/p&gt;

&lt;h3&gt;Envoyer une version : &lt;code&gt;update&lt;/code&gt;&lt;/h3&gt;

&lt;p&gt;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é &lt;strong&gt;encodé en base64&lt;/strong&gt; dans un champ texte, pas comme un fichier joint.&lt;/p&gt;

&lt;table&gt;
	&lt;thead&gt;
		&lt;tr&gt;
			&lt;th&gt;Champ&lt;/th&gt;
			&lt;th&gt;Rôle&lt;/th&gt;
		&lt;/tr&gt;
	&lt;/thead&gt;
	&lt;tbody&gt;
		&lt;tr&gt;
			&lt;td&gt;&lt;code&gt;type&lt;/code&gt;&lt;/td&gt;
			&lt;td&gt;Obligatoire : &lt;code&gt;plugin&lt;/code&gt; ou &lt;code&gt;theme&lt;/code&gt;.&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;&lt;code&gt;zip&lt;/code&gt;&lt;/td&gt;
			&lt;td&gt;Obligatoire : le paquet zip du module, en base64.&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;&lt;code&gt;category&lt;/code&gt;&lt;/td&gt;
			&lt;td&gt;Identifiant de catégorie (voir &lt;code&gt;categories&lt;/code&gt;). &lt;strong&gt;Obligatoire pour un nouveau module&lt;/strong&gt;, facultatif pour une mise à jour (la catégorie de la version courante est alors reprise).&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;&lt;code&gt;tags&lt;/code&gt;&lt;/td&gt;
			&lt;td&gt;Mots-clés séparés par des virgules (voir &lt;code&gt;tags&lt;/code&gt;). Les mots-clés inconnus du dépôt sont ignorés.&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;&lt;code&gt;license&lt;/code&gt;&lt;/td&gt;
			&lt;td&gt;Code de licence (voir &lt;code&gt;licenses&lt;/code&gt;).&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;&lt;code&gt;readme_update&lt;/code&gt;&lt;/td&gt;
			&lt;td&gt;Mettre à 1 pour reprendre le &lt;code&gt;README.md&lt;/code&gt; du paquet comme documentation de la fiche.&lt;/td&gt;
		&lt;/tr&gt;
		&lt;tr&gt;
			&lt;td&gt;&lt;code&gt;screenshot&lt;/code&gt;, &lt;code&gt;screenshot_ext&lt;/code&gt;&lt;/td&gt;
			&lt;td&gt;Une capture en base64 et son extension (&lt;code&gt;png&lt;/code&gt;, &lt;code&gt;jpg&lt;/code&gt;…), ou un zip de plusieurs images. Surtout utile aux thèmes.&lt;/td&gt;
		&lt;/tr&gt;
	&lt;/tbody&gt;
&lt;/table&gt;

&lt;p&gt;L'identifiant, le nom et la version du module sont lus dans le &lt;code&gt;_define.php&lt;/code&gt; du paquet : il doit être propre et suivre le modèle habituel, avec une version de 1 à 3 nombres (&lt;code&gt;2.5&lt;/code&gt;, &lt;code&gt;1.0.3&lt;/code&gt;, &lt;code&gt;2026.11.17&lt;/code&gt;), sans lettre ni suffixe.&lt;/p&gt;

&lt;p&gt;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 &lt;code&gt;_define.php&lt;/code&gt; (version de Dotclear requise, lien de support…).&lt;/p&gt;

&lt;h4&gt;Les règles d'une contribution&lt;/h4&gt;

&lt;ul&gt;
	&lt;li&gt;&lt;strong&gt;Une version n'existe qu'une fois&lt;/strong&gt; 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.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Une seule contribution en attente par module&lt;/strong&gt; : tant qu'une version attend la relecture des administrateurs, le module ne peut pas recevoir d'autre envoi.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Un nouveau module&lt;/strong&gt; 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.&lt;/li&gt;
&lt;/ul&gt;

&lt;h4&gt;Déposer une version plus ancienne&lt;/h4&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;Deux différences avec une mise à jour classique :&lt;/p&gt;

&lt;ul&gt;
	&lt;li&gt;&lt;strong&gt;La version de Dotclear requise est obligatoire&lt;/strong&gt; dans le &lt;code&gt;_define.php&lt;/code&gt; du paquet (&lt;code&gt;requires&lt;/code&gt; sur &lt;code&gt;core&lt;/code&gt;). 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.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;La documentation n'est pas reprise&lt;/strong&gt; de la version courante, qui ne décrit pas forcément l'ancienne : envoyez &lt;code&gt;readme_update=1&lt;/code&gt; avec un &lt;code&gt;README.md&lt;/code&gt; dans le paquet.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Les autres informations (catégorie, mots-clés, licence, lien de support…) sont reprises comme pour une mise à jour.&lt;/p&gt;

&lt;h4&gt;La réponse&lt;/h4&gt;

&lt;p&gt;En cas de succès, la réponse rappelle le module reçu, et &lt;code&gt;message&lt;/code&gt; 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) :&lt;/p&gt;

&lt;pre&gt;
&lt;code class=&quot;language-json&quot;&gt;{
  &quot;code&quot;: 200,
  &quot;message&quot;: &quot;Thank you for your submission! Your contribution is valid and online.&quot;,
  &quot;content&quot;: {
    &quot;type&quot;: &quot;plugin&quot;,
    &quot;id&quot;: &quot;monPlugin&quot;,
    &quot;name&quot;: &quot;Mon plugin&quot;,
    &quot;version&quot;: &quot;1.2&quot;
  },
  &quot;cache&quot;: &quot;0&quot;
}&lt;/code&gt;&lt;/pre&gt;

&lt;p&gt;En cas de refus, le code 108 est accompagné de la raison dans &lt;code&gt;message&lt;/code&gt; : 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.&lt;/p&gt;

&lt;h3&gt;Un exemple complet en PHP&lt;/h3&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;pre&gt;
&lt;code class=&quot;language-php&quot;&gt;&amp;lt;?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           =&amp;gt; true,
        CURLOPT_POSTFIELDS     =&amp;gt; array_filter($fields, fn ($v) =&amp;gt; $v !== ''), // jamais de champ vide
        CURLOPT_RETURNTRANSFER =&amp;gt; true,
        CURLOPT_FOLLOWLOCATION =&amp;gt; false, // ne pas renvoyer le jeton vers un autre hôte
        CURLOPT_HTTPHEADER     =&amp;gt; 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' =&amp;gt; 100, 'message' =&amp;gt; 'Réponse illisible'];
};

// 1. Jeton
$rsp = $call('auth', ['username' =&amp;gt; $login, 'password' =&amp;gt; $pass]);
if ($rsp['code'] !== 200) {
    exit('Connexion refusée : ' . $rsp['message'] . &quot;\n&quot;);
}
$token = $rsp['content']['token'];

// 2. Envoi de la version (mise à jour, version plus ancienne ou nouveau module)
$rsp = $call('update', [
    'type'          =&amp;gt; 'plugin',
    'zip'           =&amp;gt; chunk_split(base64_encode((string) file_get_contents($zip))),
    'category'      =&amp;gt; $category, // retiré par array_filter() s'il est vide
    'readme_update' =&amp;gt; '1',
    'license'       =&amp;gt; 'gpl2',
], $token);

echo $rsp['code'] . ' : ' . $rsp['message'] . &quot;\n&quot;;&lt;/code&gt;&lt;/pre&gt;

&lt;h3&gt;Bonnes pratiques pour un client&lt;/h3&gt;

&lt;ul&gt;
	&lt;li&gt;&lt;strong&gt;Toujours en https&lt;/strong&gt; : identifiant, mot de passe et jeton passent dans les requêtes.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Ne pas suivre les redirections&lt;/strong&gt; : la plupart des bibliothèques HTTP renverraient l'en-tête &lt;code&gt;Authorization&lt;/code&gt; à l'adresse de destination. Une redirection est une erreur de configuration à corriger.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Vérifier que c'est bien l'API qui répond&lt;/strong&gt; : une mauvaise adresse peut répondre 200 avec une page HTML. La présence de l'en-tête &lt;code&gt;X-RateLimit-Remaining&lt;/code&gt; sur une réponse réussie est un bon test.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Ménager le quota&lt;/strong&gt; : réutiliser le jeton, garder en mémoire les réponses identiques (les listes de référence changent rarement), et ralentir quand &lt;code&gt;X-RateLimit-NearLimit&lt;/code&gt; vaut 1.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Échapper tout ce qui vient de l'API avant de l'afficher&lt;/strong&gt; : noms, descriptions et documentations sont écrits par les contributeurs.&lt;/li&gt;
	&lt;li&gt;&lt;strong&gt;Ne garder que les champs utiles&lt;/strong&gt; : la liste des champs renvoyés peut s'enrichir ; un client doit ignorer ceux qu'il ne connaît pas.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;Pour aller plus loin&lt;/h3&gt;

&lt;p&gt;Le moteur de l'API est le plugin &lt;a href=&quot;https://dotclear.org/plugin/detail/ApiServer&quot; hreflang=&quot;en&quot;&gt;ApiServer&lt;/a&gt;, dont le &lt;a href=&quot;https://github.com/JcDenis/ApiServer/blob/master/docs/fr/utilisation.md&quot; hreflang=&quot;fr&quot;&gt;guide d'utilisation&lt;/a&gt; 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.&lt;/p&gt;</description>
        
              </item>
      </channel>
</rss>
