Le formatage des réponses des API ne suit pas vraiment de standards. Chaque API implémente des formats de réponses propres.
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.
