découvrez les différences entre interface et type en typescript, leurs usages, avantages et critères pour choisir la bonne option.

TypeScript interface ou type : quelles différences pour définir les données d’une API ?

Lorsqu’une application échange des données avec une API, les types TypeScript servent à rendre le contrat plus lisible et à repérer certaines erreurs avant l’exécution. Pour décrire un objet JSON, interface et type alias semblent souvent interchangeables. Pourtant, leurs possibilités diffèrent dès qu’il faut faire évoluer un modèle, composer plusieurs formes de données ou représenter des réponses alternatives.

Le choix devient concret dans un projet qui grandit. Une équipe peut définir un DTO pour une fiche produit, ajouter ensuite des variantes selon le contexte, puis partager ces contrats entre le serveur et le client. Comprendre l’extensibilité, la fusion de déclarations, les types union et les types intersection permet de choisir une forme adaptée, sans confondre vérification statique et validation réelle des données reçues.

En bref

  • interface convient particulièrement aux formes d’objets appelées à être étendues ou augmentées.
  • type alias représente les objets, mais aussi les unions, les intersections, les primitives et les tuples.
  • Pour un DTO d’API, les deux options décrivent le contrat statique ; aucune ne vérifie seule le JSON à l’exécution.
  • La cohérence des réponses, les conventions de l’équipe et les besoins d’évolution comptent davantage qu’une règle absolue.

TypeScript pour une API : ce que changent interface et type alias

Imaginons une boutique en ligne fictive, Atelier Nord, dont l’API renvoie une fiche produit. L’objet contient un identifiant, un nom, un prix et un état de disponibilité. Une interface peut exprimer cette forme : les propriétés sont nommées, leurs types sont explicites et le modèle se lit comme un contrat d’objet. Un type alias peut décrire la même structure avec une syntaxe presque équivalente. Dans les deux cas, TypeScript compare principalement les formes, et non le nom donné au modèle.

Cette approche est dite structurelle. Si une fonction attend un objet contenant un identifiant numérique et un nom textuel, elle peut recevoir toute valeur qui possède ces propriétés compatibles, même si cette valeur a été déclarée ailleurs. Pour une API, cette souplesse facilite le passage d’un DTO à une fonction métier, mais elle ne garantit pas que le serveur a réellement envoyé ces champs. Elle indique seulement au compilateur comment le code prétend les utiliser.

Par exemple, une développeuse peut écrire le type d’une réponse comme si chaque produit comportait toujours un prix. Si l’API renvoie exceptionnellement null, le typage ne transformera pas la donnée reçue : une erreur apparaîtra seulement si le contrat statique a été défini de manière assez précise et si le code manipule la valeur sans précaution. Une annotation de type ne nettoie donc pas le JSON et ne remplace pas une validation à l’exécution.

Un contrat lisible pour les données échangées

Le premier critère de choix est souvent la lecture. Dans une base de code où les modèles sont principalement des objets nommés — Client, Commande, Produit — les deux syntaxes restent accessibles. L’interface met visuellement l’accent sur la forme d’un objet, tandis que le type alias rappelle qu’un nom peut désigner une composition plus générale. Cette distinction devient utile lorsque les réponses de l’API ne sont pas toutes de simples objets homogènes.

Les équipes qui souhaitent consolider leurs bases peuvent associer ces exemples à un exercice pratique, comme un projet e-commerce pour apprendre TypeScript. En définissant les réponses du catalogue, du panier et du paiement, la différence entre un modèle d’objet et un ensemble de variantes devient plus facile à observer. Le choix de syntaxe prend alors sens par rapport aux transformations réelles de l’application.

Pour Atelier Nord, la fiche produit principale peut rester une interface, alors qu’une réponse de recherche peut réunir plusieurs sortes de résultats. Cette séparation évite de forcer tous les cas dans un seul objet rempli de propriétés optionnelles. Le bon point de départ consiste à identifier la forme réelle des réponses, avant de choisir la syntaxe qui la décrit.

découvrez les différences entre interface et type en typescript, leurs avantages, leurs limites et quand utiliser chacun.

Interface TypeScript : extensibilité et fusion de déclarations pour un DTO

Une interface est particulièrement adaptée lorsqu’un modèle d’objet doit être étendu au fil du projet. Une interface de base peut décrire les propriétés communes d’un produit, puis une autre interface peut la prolonger avec des champs propres à une page de détail. Cette relation rend visible la hiérarchie du contrat : le produit détaillé conserve les propriétés du produit standard et ajoute, par exemple, une description longue ou une galerie d’images.

Cette extensibilité est utile lorsque plusieurs équipes consomment le même modèle. Une interface partagée peut servir de fondation, puis des interfaces spécialisées précisent les données nécessaires à une vue ou à une opération donnée. Il reste toutefois important de ne pas confondre l’extension d’un modèle et la création d’un DTO différent. Une réponse d’API publique ne devrait pas hériter aveuglément de champs internes simplement parce que cela réduit quelques lignes de code.

Étendre un contrat sans dupliquer ses propriétés

Dans une boutique, une interface Product peut décrire l’identifiant, le libellé et le prix. ProductDetail peut étendre ce premier contrat avec la description et la liste des images. Cette organisation indique que tout produit détaillé est aussi un produit de base. Le compilateur peut alors vérifier qu’une valeur destinée à l’écran de détail contient bien les propriétés requises par cette vue, tandis que les composants plus simples restent libres de ne demander que les données essentielles.

Une autre caractéristique propre aux interfaces est la fusion de déclarations. Lorsque plusieurs déclarations portant le même nom apparaissent dans un contexte prévu pour cela, TypeScript les rassemble. Ce mécanisme sert notamment à enrichir des types provenant de bibliothèques ou à déclarer des extensions de modules. Il peut être pratique, mais il exige une discipline : deux définitions éloignées peuvent modifier le même contrat et rendre son contenu moins évident à retrouver.

Pour un DTO d’API interne, la fusion automatique n’est généralement pas nécessaire. Il est souvent plus clair d’utiliser une interface distincte et une extension explicite, plutôt que de disperser des déclarations qui se complètent implicitement. Cette précaution aide lors d’une revue de code : la personne qui lit le modèle voit immédiatement les champs hérités et les champs ajoutés, sans devoir chercher toutes les déclarations du même nom.

Quand la fusion aide, et quand elle brouille le contrat

La fusion peut être justifiée quand un module doit enrichir un type global ou une définition fournie par un outil. En revanche, si deux versions d’un contrat HTTP sont fusionnées par accident, le résultat peut suggérer qu’une réponse contient des champs qui ne sont pas réellement présents dans tous les cas. Le danger n’est pas seulement stylistique : une définition trop permissive encourage le code à accéder à des données absentes.

Avant d’étendre une interface, il est donc utile de vérifier la relation métier. Un détail de produit est bien une spécialisation d’un produit ; une erreur d’API n’est pas un produit avec quelques champs optionnels. Pour les erreurs, un modèle séparé, voire une union discriminée, exprime mieux le comportement. L’interface favorise une extension explicite des objets, tandis que la fusion de déclarations doit rester un outil ciblé plutôt qu’un raccourci ordinaire.

Cette manière de distinguer les modèles aide aussi à structurer le serveur. Une ressource peut être exposée par des routes dédiées, comme dans un tutoriel sur la création d’une API REST avec Node.js. Le contrat TypeScript devient alors le reflet raisonné de chaque réponse, plutôt qu’un objet universel supposé couvrir toutes les routes.

Type alias TypeScript : types union, types intersection et réponses variables

Le type alias devient particulièrement expressif lorsque la donnée n’est pas un seul objet fixe. Il peut désigner une union, une intersection, un tuple, une primitive ou une forme d’objet. Une interface, elle, décrit une forme d’objet et peut être étendue, mais ne sert pas directement à exprimer « cette valeur est l’un ou l’autre de plusieurs types ». Pour les réponses d’API qui varient selon le résultat ou l’état d’une opération, cette différence est déterminante.

Dans Atelier Nord, une recherche peut renvoyer un produit ou une catégorie. Un type union permet de représenter ces possibilités sous un même nom, à condition que le code puisse distinguer les variantes. Un champ littéral commun, par exemple kind avec la valeur product ou category, sert de discriminant. Après vérification de cette valeur, TypeScript sait quelles propriétés sont disponibles. Le contrat décrit ainsi les scénarios réels plutôt qu’un objet surchargé de champs facultatifs.

Une union pour distinguer les cas d’une réponse

Une requête de paiement peut également aboutir à un résultat accepté ou refusé. Une réponse acceptée peut contenir un identifiant de transaction, tandis qu’un refus fournit un code d’erreur et un message. Si un modèle unique rend ces trois propriétés optionnelles, le code doit constamment deviner lesquelles existent. Une union discriminée rend les états explicites : après avoir testé l’état, l’application accède au champ propre au cas concerné.

Ce type de modélisation est utile côté client, car il évite de présenter une transaction comme réussie lorsqu’elle ne l’est pas. Il facilite aussi les tests : chaque variante peut être construite et vérifiée séparément. Le contrat reste toutefois fidèle à l’API seulement si celle-ci renvoie vraiment un discriminant ou des structures reconnaissables. Si le serveur ne fournit aucun moyen fiable de distinguer les formes, le modèle TypeScript ne peut pas inventer une certitude qui n’existe pas dans les données.

Une intersection pour composer des propriétés

Les types intersection combinent plusieurs contraintes. Par exemple, une base commune portant un identifiant et une date de création peut être associée à un ensemble de propriétés de produit. Cela permet de composer des éléments transversaux, comme des métadonnées, avec un modèle métier. Toutefois, une intersection n’est pas simplement une fusion visuelle : les propriétés incompatibles peuvent produire un type impossible ou peu utile. Si une définition impose un champ sous forme de chaîne et une autre sous forme de nombre, la valeur devrait satisfaire les deux exigences à la fois.

Il faut donc réserver l’intersection aux compositions cohérentes. Pour une ressource qui possède plusieurs variantes alternatives, l’union est généralement plus adaptée ; pour un objet qui cumule réellement plusieurs groupes de propriétés, l’intersection peut clarifier la construction. La distinction est importante lors d’une révision : « l’un ou l’autre » appelle une union, tandis que « les deux à la fois » appelle une intersection.

Le vocabulaire ne doit pas devenir une fin en soi. Une équipe gagne surtout à exprimer les états que l’application traite, et à rendre chaque accès aux propriétés compréhensible. Le type alias prend l’avantage dès que le contrat doit représenter plusieurs formes possibles ou des compositions qui dépassent un objet unique.

Définir un DTO d’API : interface ou type selon le contrat

Un DTO, ou objet de transfert de données, décrit les informations qui circulent entre deux parties d’une application. Pour une API, il peut correspondre au corps d’une requête, à une réponse ou à une représentation adaptée à un écran. Employer le même modèle partout paraît économique, mais crée souvent des confusions : les données envoyées pour créer une ressource ne sont pas nécessairement celles renvoyées après sa création, et les propriétés internes ne doivent pas forcément être exposées.

Atelier Nord peut distinguer CreateProductRequest, ProductResponse et ProductDetailResponse. Le premier contient les informations saisies par une personne autorisée, sans identifiant généré par le serveur. La réponse comprend cet identifiant et éventuellement une date de création. La vue détaillée ajoute les données nécessaires à une page précise. Ces noms rendent les usages visibles et évitent qu’une seule interface générale devienne un compromis imprécis.

Séparer création, lecture et mise à jour

Une création et une mise à jour n’ont pas toujours les mêmes contraintes. Une création peut exiger un nom et un prix, tandis qu’une modification partielle ne fournit que les champs à changer. Réutiliser le type complet en rendant toutes les propriétés optionnelles peut sembler simple, mais ne distingue plus une mise à jour partielle d’une réponse incomplète. Des modèles dédiés décrivent mieux chaque opération et rendent les erreurs de validation plus faciles à interpréter.

La même logique vaut pour les listes et les détails. Une réponse de liste peut contenir un identifiant, un nom et une miniature, alors qu’une page dédiée requiert une description, des images et des caractéristiques. Définir un contrat spécifique à chaque route évite de télécharger ou de supposer des données absentes. Le choix entre interface et type peut alors suivre le besoin : interface pour une structure d’objet stable et extensible, type alias quand la réponse comporte des variantes ou des compositions.

Besoin pour l’APIChoix souvent adaptéRaison
Objet DTO nommé et extensibleinterfaceLa structure se prolonge explicitement avec extends.
Réponse parmi plusieurs étatstype aliasLes types union expriment les variantes.
Composition de plusieurs contraintestype aliasLes types intersection combinent des formes compatibles.
Enrichissement contrôlé d’une définitioninterface, avec prudenceLa fusion de déclarations peut être utile, mais doit rester intentionnelle.

Ce tableau donne des repères, pas une obligation universelle. Une équipe peut choisir une convention cohérente et la documenter, surtout si les contrats sont partagés entre front-end et serveur. Des outils de schéma peuvent aussi générer des définitions à partir d’une spécification, ce qui réduit les divergences, à condition de vérifier que les types produits correspondent à la façon dont l’application consomme réellement la réponse.

Préserver la cohérence des modèles partagés

Un contrat partagé n’est pas toujours un contrat à exposer tel quel. Un modèle interne peut contenir des données de gestion, alors que l’API doit seulement publier un sous-ensemble. Créer une transformation explicite entre la donnée métier et le DTO rend cette frontière vérifiable. Cela évite qu’une évolution interne ajoute involontairement un champ sensible à la réponse publique.

Pour un projet utilisant un ORM, les modèles de base de données et les DTO répondent à des objectifs distincts. Un outil tel que Prisma facilite l’accès aux données, mais ses types générés ne remplacent pas automatiquement les contrats HTTP. La frontière entre stockage et API doit rester intentionnelle. Un DTO utile décrit l’échange attendu par une route, pas simplement la structure la plus proche déjà disponible dans le projet.

Choisir entre interface et type pour une API robuste

Dans la pratique, le choix se prend en examinant la forme et l’évolution prévues du contrat. Si la donnée est un objet nommé, stable et susceptible d’être étendu, une interface est un choix naturel. Si le modèle doit réunir plusieurs réponses possibles, inclure une union ou composer des éléments par intersection, un type alias offre les outils adaptés. Rien n’empêche non plus une base de code d’utiliser les deux : la cohérence vient de la raison du choix, pas d’une uniformité imposée à toutes les situations.

Une méthode simple consiste à partir des routes et des exemples JSON. Pour chaque opération, il faut relever les propriétés toujours présentes, celles qui peuvent être absentes, celles qui peuvent valoir null, puis les variantes de réponse. Cette étape distingue trois situations souvent confondues : propriété facultative, valeur nullable et branche alternative. Une propriété facultative peut manquer ; une valeur nullable est présente mais peut valoir null ; une union décrit plusieurs formes distinctes.

Une vérification en plusieurs étapes

  1. Recenser les réponses réelles. Comparer les cas normaux, les erreurs et les résultats particuliers évite de concevoir le contrat sur un seul exemple favorable.
  2. Définir les DTO par opération. Séparer création, lecture, mise à jour et erreur clarifie les responsabilités de chaque route.
  3. Choisir la forme TypeScript. Utiliser une interface pour une structure d’objet extensible, ou un type alias pour une union, une intersection ou une autre forme composable.
  4. Valider à l’exécution. Contrôler le JSON reçu avec un schéma ou une validation dédiée, car le compilateur n’inspecte pas les réponses réseau au moment où elles arrivent.
  5. Tester les scénarios limites. Vérifier les champs manquants, les valeurs nulles et chaque branche empêche le contrat de ne couvrir que le parcours idéal.

Cette démarche répond à un point essentiel : TypeScript garantit la cohérence du code par rapport aux types déclarés, mais ne prouve pas que le serveur respecte ces déclarations. Une application qui reçoit du JSON externe doit traiter cette donnée comme inconnue jusqu’à ce qu’elle soit vérifiée. Une bibliothèque de validation peut partager certains schémas entre les couches ou produire des types à partir de définitions, mais le choix de l’outil dépend de l’architecture.

La convention d’équipe comme facteur de qualité

Dans un dépôt partagé, il est utile de documenter quelques règles concrètes. Par exemple : interfaces pour les objets de domaine extensibles, types alias pour les unions discriminées, et DTO séparés par opération lorsque les entrées et sorties diffèrent. Ces règles accélèrent les revues de code, car la personne qui lit une définition comprend pourquoi elle a cette forme. Elles doivent rester assez souples pour ne pas contraindre un modèle atypique à une abstraction inadaptée.

Une petite équipe peut commencer par une convention minimale, puis la faire évoluer après avoir rencontré de vrais besoins de composition ou d’extension. Une grande base de code, elle, gagne à automatiser les contrôles et à vérifier les spécifications de ses routes. Dans les deux cas, l’exemple d’une API construite avec un runtime comme Deno peut illustrer la séparation entre environnement serveur et contrat de données ; le runtime ne change pas les capacités fondamentales de TypeScript.

La décision finale peut se résumer sans dogme : interface pour nommer et faire évoluer une forme d’objet, type alias pour exprimer un ensemble plus général de possibilités. La robustesse d’une API repose surtout sur des DTO fidèles, une validation effective et une convention compréhensible par toute l’équipe.

{« @context »: »https://schema.org », »@type »: »FAQPage », »mainEntity »:[{« @type »: »Question », »name »: »Une interface et un type alias sont-ils interchangeables pour un objet ? », »acceptedAnswer »:{« @type »: »Answer », »text »: »Dans de nombreux cas, oui : les deux peuvent du00e9crire la mu00eame forme du2019objet et TypeScript compare leurs propriu00e9tu00e9s de fau00e7on structurelle. Lu2019interface se pru00eate particuliu00e8rement u00e0 lu2019extension et u00e0 la fusion de du00e9clarations, tandis que le type alias peut aussi repru00e9senter des unions, des intersections, des tuples ou des primitives. »}},{« @type »: »Question », »name »: »Quel choix privilu00e9gier pour un DTO du2019API ? », »acceptedAnswer »:{« @type »: »Answer », »text »: »Pour un DTO qui du00e9crit un objet stable et extensible, une interface est un choix courant. Un type alias convient mieux lorsque la ru00e9ponse peut prendre plusieurs formes ou combine des types. Il est souvent pru00e9fu00e9rable de du00e9finir un DTO distinct pour chaque opu00e9ration plutu00f4t que de ru00e9utiliser un modu00e8le gu00e9nu00e9ral impru00e9cis. »}},{« @type »: »Question », »name »: »Les types TypeScript valident-ils les ru00e9ponses JSON reu00e7ues ? », »acceptedAnswer »:{« @type »: »Answer », »text »: »Non. Les types TypeScript servent u00e0 vu00e9rifier le code pendant la compilation et ne contru00f4lent pas automatiquement les donnu00e9es ru00e9seau u00e0 lu2019exu00e9cution. Une validation avec un schu00e9ma ou une fonction du00e9diu00e9e reste nu00e9cessaire pour vu00e9rifier le contenu reu00e7u. »}},{« @type »: »Question », »name »: »Quand utiliser une union discriminu00e9e dans une API ? », »acceptedAnswer »:{« @type »: »Answer », »text »: »Elle est utile quand une ru00e9ponse peut repru00e9senter plusieurs u00e9tats ou ressources distinctes, comme un paiement acceptu00e9 ou refusu00e9. Un champ discriminant permet au code du2019identifier la variante et du2019accu00e9der aux propriu00e9tu00e9s correspondantes sans multiplier les champs optionnels. »}}]}

Une interface et un type alias sont-ils interchangeables pour un objet ?

Dans de nombreux cas, oui : les deux peuvent décrire la même forme d’objet et TypeScript compare leurs propriétés de façon structurelle. L’interface se prête particulièrement à l’extension et à la fusion de déclarations, tandis que le type alias peut aussi représenter des unions, des intersections, des tuples ou des primitives.

Quel choix privilégier pour un DTO d’API ?

Pour un DTO qui décrit un objet stable et extensible, une interface est un choix courant. Un type alias convient mieux lorsque la réponse peut prendre plusieurs formes ou combine des types. Il est souvent préférable de définir un DTO distinct pour chaque opération plutôt que de réutiliser un modèle général imprécis.

Les types TypeScript valident-ils les réponses JSON reçues ?

Non. Les types TypeScript servent à vérifier le code pendant la compilation et ne contrôlent pas automatiquement les données réseau à l’exécution. Une validation avec un schéma ou une fonction dédiée reste nécessaire pour vérifier le contenu reçu.

Quand utiliser une union discriminée dans une API ?

Elle est utile quand une réponse peut représenter plusieurs états ou ressources distinctes, comme un paiement accepté ou refusé. Un champ discriminant permet au code d’identifier la variante et d’accéder aux propriétés correspondantes sans multiplier les champs optionnels.

Publications similaires