L’API de Da Button Factory

Version 2, disponible depuis le .
Dernière révision mineure le (nom des polices dorénavant insensible à la casse).

Sommaire

Aperçu

L’API de Da Button Factory rend possible la génération dynamique et automatisée de boutons.
Elle renvoit une image de bouton en réponse à une requête HTTP utilisant la méthode GET.
Les paramètres du bouton, comme son texte, sa taille, ou sa couleur, sont renseignés dans son URL.

Le format d’une URL de bouton est le suivant : https://DaButtonFactory.com/button.<format fichier>?<paramètre 1>&<paramètre 2>&<paramètre n>

La partie <format fichier> indique le format de fichier image voulu. Les valeurs valides sont : png, gif, jpg, ou ico.
Les <paramètres> indiquent tout le reste (le texte, la bordure, les couleurs, …). La liste détaillée des paramètres se trouve dans la section suivante.

Par exemple, l’API renvoit l’image suivante pour l’URL donnée ci-dessous :
generated buttonhttps://DaButtonFactory.com/button.png?t=Hello,+API!&ts=24&bgt=gradient&bgc=afa&ebgc=5e5&c=5&bs=1

Notre application web pour créer des boutons utilise cette API REST en coulisse.
Quand vous utilisez l’application, vous pouvez trouver l’URL du bouton en cours d’édition en déroulant la section « Intégrer ».

Spécification des paramètres

Les paramètres sont définis dans la query string de l’URL (la partie qui se trouve après le point d’interrogation), séparés par des esperluettes (&).
Ils peuvent être définis dans n’importe quel ordre. Ils sont tous optionnels ; une valeur par défaut est utilisée si un paramètre n’est pas défini explicitement.
Un paramètre se compose d’un nom et d’une valeur, séparés par un signe égal (=).
La valeur doit être encodée si elle contient des caractères spéciaux nécessitant l’emploi de séquences d'échappement.

Une Taille est un nombre entier compris dans l’interval 0↔1000 (bornes inclusives). Toutes les tailles sont en pixels (y compris la taille de la police).

Une Couleur est un triplet de valeurs RVB exprimé en hexadécimal. Par exemple : ff0000 (rouge pur), 00ff00 (vert pur).
Une couleur peut aussi être donnée en notation hexadécimale courte (comme en CSS). Par exemple : 00f (bleu pur, équivalent à 0000ff).

Liste complète des paramètres :
NomDescriptionValeurs possibles / formatValeur par défaut
tTexte du boutonune chaîne de caractères (encodée en UTF-8)aucun
fPolice d'écriture
  • Calibri
  • Open Sans
  • Ubuntu
  • Roboto
  • Caviar
  • Zenhei
  • Noto Sans
  • Droid Serif
  • Vollkorn
  • Pagella
  • Playfair Display
  • Arvo
  • Komika
  • Pacifico
  • Lobster Two
  • Overlock
  • Bellota

Suffixez le nom de la police avec :
  • -Bold pour utiliser la variante grasse de la police
  • -Italic pour utiliser la variante italique de la police
  • -Bold-Italic pour utiliser la variante grasse-italique de la police
Zenhei et Pacifico ne sont pas disponibles en gras et/ou italique.
Calibri
tcCouleur du texteune Couleur#000
tsTaille du texteune Taille12
tshsDistance entre le texte et son ombre.
Si définie à 0, aucune ombre n’est présente.
une Taille0
tshcCouleur de l’ombre du texteune Couleur#777
cArrondi des coins ou des côtés.
Si défini à 0, le bouton a des angles droits.
Si défini à round, les côtés gauche et droit du boutons forment un cercle.
une Taille, ou la valeur spéciale round0
bgtType d’arrière-plan
  • unicolored
  • two-colors
  • gradient
  • pyramid
unicolored
bgcCouleur du haut de l’arrière-plan si le type est two-colors ou gradient.
Couleur du haut et du bas si le type est pyramid.
Couleur de l’arrière-plan entier si le type est unicolored.
une Couleur#00f
ebgcCouleur du bas de l’arrière-plan si le type est two-colors or gradient.
Couleur centrale si le type est pyramid.
Paramètre ignoré si le type est unicolored.
une Couleur#0ff
bsTaille de la bordure.
Si définie à 0, aucune bordure n’est présente.
une Taille0
bcCouleur de la bordureune Couleur#888
shsTaille de l’ombre du bouton.
Si définie à 0, aucune ombre n’est présente.
une Taille0
shcCouleur de l’ombre du boutonune Couleur#666
shoOrientation de l’ombre du bouton
  • une direction verticale : n pour nord, ou s pour sud
  • une direction horizontale : w pour ouest, ou e pour est
  • une combinaison des deux (e.g : nw pour nord-ouest)
se
be« Effet bulle » ; reflet de forme elliptique sur la moitié supérieure du bouton
  • 0 (pas d’effet)
  • 1 (effet présent)
0
hpMarge entre le texte et les extrémités gauche et droite du boutonune Taille12
vpMarge entre le texte et les extrémités haut et bas du boutonune Taille10
wLargeur (taille horizontale) du bouton.
Sans compter la taille de la bordure et/ou de l’ombre.
A précédence sur hp.
une Taillenone
hHauteur (taille verticale) du bouton.
Sans compter la taille de la bordure et/ou de l’ombre.
A précédence sur vp.
une Taillenone

Codes de réponse

Le code de réponse HTTP est :

  • 200 OK si le bouton a été généré avec succès.
  • 400 Bad Parameter si l’un des paramètres a une valeur erronée.
  • 400 Too Big si la taille du bouton excède les limites.
  • 500 Internal Error s’il y a un problème de notre côté.

Le corps de la réponse est l’image du bouton (un flot de données binaires) si la génération a réussi.
En cas d’erreur, c’est un message explicatif au format texte (text/plain).

Limites et conditions d’utilisation

Le nombre de pixels dans un bouton est limité à 250 000 au maximum.
Toute Taille doit être comprise entre 0 et 1000 (pixels).
Une URL de bouton ne peut pas dépasser 4096 caractères.

Faire un lien direct vers l’URL d’un bouton est permis. Les boutons fréquemment utilisés sont mis en cache par notre CDN.
Mais si vous prévoyez de générer plusieurs nouveaux boutons par minute, merci d’en discuter avec nous au préalable.
Nous nous réservons le droit de bloquer toute utilisation de l’API qui nous paraîtrait abusive, et ce sans préavis.

Aucune garantie n’est fournie quant à cette API (concernant, par exemple, sa disponibilité).
Nos performances passées sont cependant très bonnes : plus de 6 ans sans interruption majeure de service.
Soyez responsables et faites un don si vous voulez que ça continue ainsi !