Convertisseur de texte
HTML ◄--► BBcode

Les champs retournés par l'API de conversion

Vous trouverez ici la description de chaque valeur retournée par l'API de conversion de textes. Le résultat est au format JSON. Comme pour tout langage structuré (XML, HTML...), vous n'avez pas besoin de coder votre propre parseur de JSON, le langage que vous utilisez propose forcément des fonctions ou librairies prêtes à l'emploi. En PHP par exemple, utilisez la fonction json_decode() pour transformer le flux textuel JSON en un array ou objet manipulable.

Structure de l'API JSON

Si vous vous voulez aller à l'essentiel, lisez les clés marquées [important].


api_version

Type : chaîne de caractères
Niveau : 2 (dépend de metas)
Exemple de valeur : 1.0

Affiche le numéro de version exact de l'API que vous avez appelée, sous la forme « [version majeure].[version mineure] ».


api_status

Type : chaîne de caractères
Niveau : 2 (dépend de metas)
Valeurs possibles : un des codes listés ci-dessous.


datetime_utc

Type : chaîne de caractères
Niveau : 2 (dépend de metas)
Exemple de valeur : 2017-08-14T21:38:31+00:00

Affiche la date à laquelle l'API a été générée, à l'heure UTC. UTC est le « temps universel », indépendant des fuseaux horaires, des changements d'heure hiver/été et de l'heure du pays qui héberge le site. A titre indicatif, voici les correspondances de l'UTC avec les heures quelques pays :
- France, Belgique : ajouter 1 heure en hiver ou 2 heures en été
- Pays-Bas : ajouter 1 heure
- Royaume-Uni : heure UTC
- États-Unis (ouest) : soustraire 5 heures
- États-Unis (est) : soustraire 8 heures

La date est rédigée au format standard ISO 8601 (ex : 2017-08-14T21:38:31+00:00). Des fonctions pour manipuler ce format de date existent dans tous les langages. En PHP par exemple, vous pouvez la convertir en timestamp avec la fonction strtotime() :

// Convertit la date UTC en timetamp UNIX (1502746711)
$timestamp = strtotime('2017-08-14T21:38:31+00:00');
// Convertit le timestamp en date française (14-08-2017 23h08)
echo date('d-m-Y H\hm', $timestamp);

error_alias

Type : chaîne de caractères
Niveau : 2 (dépend de error)
Valeurs possibles : un des codes d'erreurs listés ci-dessous.

Retourne un code indiquant la nature de l'erreur rencontrée, ou success si la conversion s'est bien réalisée. Ces codes d'erreurs sont invariables, vous pouvez les utiliser dans vos scripts pour identifier les erreurs et les traiter en conséquence.


error_message

Type : chaîne de caractères
Niveau : 2 (dépend de error)
Exemple de valeur : The URL you sent is invalid.

Affiche un court message décrivant l'erreur qui a été rencontrée, en fonction de la valeur de la clé error_alias. Si votre script ne prévoit pas de message pour certaines erreurs, vous pouvez afficher par défaut la valeur de cette clé à vos utilisateurs. Il sera plus explicite que la valeur de error_alias ou qu'un vague « erreur inattendue ».

N'utilisez pas cette clé pour détecter le type d'erreur rencontré. Pour cela, utilisez la valeur de la clé error_alias.


orig_language_id

Type : nombre entier (integer)
Niveau : 2 (dépend de options_set)
Exemple de valeur : 8

Affiche l'ID que vous avez indiqué comme langage d'origine, c'est-à-dire le langage avec lequel est balisé le texte que vous voulez convertir. Par exemple, si votre texte a été rédigé en Markdown et que vous voulez le convertir en HTML, le langage d'origine est le Markdown. Voir paramètres d'appel à l'API > orig_language_id.


destin_language_id

Type : nombre entier (integer)
Niveau : 2 (dépend de options_set)
Exemple de valeur : 12

Affiche l'ID que vous avez indiqué comme langage de destination, c'est-à-dire le langage vers lequel vous voulez convertir votre texte. Par exemple, si votre texte a été rédigé en Markdown et que vous voulez le convertir en HTML, le langage de destinationest le HTML. Voir paramètres d'appel à l'API > destin_language_id.


page_url

Type : chaîne de caractères
Niveau : 2 (dépend de options_set)
Exemple de valeur : https://domain.here/page.html

Affiche l'URL de la page source à convertir, si vous l'aviez fournie. Ce paramètre permet de transformer les éventuels liens relatifs contenus dans votre texte en liens absolus.


Type : booléen
Niveau : 2 (dépend de options_set)
Valeurs possibles : 0 ou 1

Indique si vous avez activé ou non le paramètre repair_relative_links.


return_html_preview

Type : booléen
Niveau : 2 (dépend de options_set)
Valeurs possibles : 0 ou 1

Indique si vous avez activé ou non le paramètre return_html_preview.


return_unknown_tags_list

Type : booléen
Niveau : 2 (dépend de options_set)
Valeurs possibles : 0 ou 1

Indique si vous avez activé ou non le paramètre return_unknown_tags_list.


remove_unknown_tags

Type : booléen
Niveau : 2 (dépend de options_set)
Valeurs possibles : 0 ou 1

Indique si vous avez activé ou non le paramètre remove_unknown_tags.


prettify_json

Type : booléen
Niveau : 2 (dépend de options_set)
Valeurs possibles : 0 ou 1

Indique si vous avez activé ou non le paramètre prettify_json.


converted_text

Type : texte
Niveau : 1 (racine)

Il s'agit de la clé la plus importante de l'API puisqu'elle elle contient le texte converti.

La clé converted_text n'existe que si error_alias vaut "success", c'est-à-dire lorsqu'aucune erreur n'a été rencontrée lors de la conversion. Il s'agit d'un garde-fou au cas où un utilisateur aurait mal conçu son script d'appel à l'API.

Pourquoi cette sécurité ?
Lorsque le convertisseur lève une erreur critique dans error_alias, la clé converted_text sera généralement vide. Un script mal conçu qui récupèrerait le contenu de converted_text sans avoir contrôlé préalablement la valeur de error_alias enregistrerait donc des textes vides à l'insu de son développeur. L'absence de la clé converted_text en cas d'erreur pallie ce défaut de conception : le script utilisateur plantera complètement et son développeur verra immédiatement qu'il y a un problème.

Naturellement, comme vous n'êtes pas ce développeur distrait, vos scripts à vous contrôlent la valeur de error_alias. ;)


html_preview

Type : texte
Niveau : 1 (racine)

Contient le même aperçu HTML que celui présent sur la version en ligne du convertisseur. Cette clé n'est présente que si vous avez activé le paramètre return_html_preview.


unknown_tags_list

Type : tableau
Niveau : 1 (racine)

Liste des balises qui n'ont pas été reconnues lors de la conversion. Cette clé n'est présente que si vous avez activé le paramètre return_unknown_tags_list. Si vous l'avez activé mais que toutes les balises ont été reconnues, le tableau sera vide.