Écrire des Types de réponses forts pour ses API en TypeScript

⏱ Temps de lecture : 5 mins

Le formatage des réponses des API ne suit pas vraiment de standards. Chaque API implémente des formats de réponses propres.


Le typage fort des réponses de vos API en TypeScript


L’objectif de cet article n’est pas de proposer un standard de réponse. Il va étudier en profondeur le typage fort de ce formatage.

Peu importe le format de retour que vous souhaitez implémenter, le typage se doit d'être bon.


Typiquement, une réponse inclut des champs standards tels que le statut, l'erreur, etc.


L’erreur : Typer les API TypeScript à l’aide de types optionnels


Le flux d’appel d'une API est le suivant :

  • Le client appelle l’API.
  • L’API valide les valeurs entrantes (input) et renvoie un form_errors si ces données sont mauvaises.
  • L’API traite la demande et renvoie la réponse dans data ou une erreur si quelque chose se passe mal.


La solution de facilité serait d’implémenter le typage suivant :



Un œil expérimenté va vite repérer le problème :

Il n’y a aucune certitude sur le typage de retour. Même si le status est ok, il faudra vérifier que data n’est pas undefined avant de pouvoir réaliser la moindre opération.


Par exemple, lors de la consommation de l’API :


Ce typage a une efficience proche de 0.


Une solution : les types discriminants de TypeScript pour les API


Dans notre cas, il faut utiliser la puissance de TypeScript, en particulier, sa capacité d’inférence pour pouvoir construire un typage fort et structuré des réponses de l’API.


Un type discriminant utilise un marqueur, une propriété, qui discrimine le type. Grâce à l’inférence de type, TypeScript sait, en fonction de ce marqueur, quel type est utilisé.


Voici l’exemple complet qui illustre le fonctionnement (j’ai volontairement omis la gestion d’erreur dans l’exemple pour que ce soit plus clair)


status est la propriété discriminante entre les trois types de retour de l’API. Le type ApiData prend donc les trois, à l’aide de | (OR).


Lorsque l’on fait un appel, le discriminant est analysé pour savoir dans quel type on se trouve. Et à chaque fois, TypeScript infère le type de l’objet en fonction de ce discriminant.


La définition des types s’en trouve alors bien plus robuste et beaucoup plus lisible pour les parties prenantes de l’API.


Vous voulez plus de tips sur TypeScript ? N’hésitez pas à parcourir ce blog.


Vous voulez vous perfectionner sur TypeScript avec un vrai professionnel ? Consultez nos formations.

En résumé

  • Le typage des retours d'une API en TypeScript est aussi important que la standardisation de ces retours.
  • Il faut éviter les types optionnels qui ne permettent pas une prédiction correcte du format de retour.
  • Pour solutionner ce problème, les types discrimimant et l'inférence permettent un typage fort.

Partager cet article

Qui sommes-nous ?

Mon Formateur Indépendant est un collectif d'experts du secteur du digital.


Nous proposons des formations professionnelles et des accompagnements sur-mesure sur le développement web, la cybersécurité, le SEO et le marketing digital.


Ecrit par : Thomas Dupont

photo de profil de Thomas Dupont


Avec une double casquette de développeur et de contrôleur financier, Thomas allie une expertise technique en développement web à de solides connaissances en gestion d'entreprise. Cette combinaison unique lui permet de comprendre et d'agir efficacement sur les problématiques de ses clients.
En tant que développeur web depuis 10 ans, Thomas maîtrise les technologies et langages web comme JavaScript, TypeScript et Node.js.
Il est intervenu pour des sociétés prestigieuses telles que L'Oréal, Louis Vuitton ou Chanel et travaille sur des applications comptabilisant des centaines de milliers d'utilisateurs actifs.
Il vous apportera une vraie vision orientée solutions.