TypeSpec : un nouveau langage pour le développement centré sur les API

 (typespec.io)
6 points par GN⁺ 2024-05-02 | 1 commentaires | Partager sur WhatsApp
  • TypeSpec est un nouveau langage pour le développement centré sur les API, conçu pour répondre aux besoins des développeurs, des concepteurs et des responsables d’API
    • Conçu dans un contexte où fournir des API de qualité constante et des expériences associées devient de plus en plus complexe et important
    • TypeSpec est plus qu’un simple langage : c’est une plateforme qui permet l’abstraction, encourage la réutilisation du code et s’appuie sur des outils modernes pour un développement rapide

Principales caractéristiques de TypeSpec

  • Interopérabilité
    • TypeSpec n’est pas un simple langage de description d’API, mais un langage de définition de haut niveau pour définir des API et générer simultanément divers protocoles, clients, serveurs, documentation, etc.
    • Il est interopérable avec les langages de définition d’API standards de l’industrie, ce qui réduit les écarts entre les différentes options
  • Productivité
    • TypeSpec offre une excellente expérience développeur pour rendre le travail sur les données et la définition d’API plus fluide et productif
    • Le langage est concis et permet de définir des formes de données et d’API complexes avec un minimum d’entrées
  • Modèles d’API
    • TypeSpec encapsule les types de données courants, les patterns d’API et les directives dans des composants réutilisables de haut niveau partageables à l’échelle d’une équipe ou d’un écosystème, améliorant ainsi la qualité des API
  • Familiarité
    • TypeSpec s’inspire de TypeScript et C# pour être facile à apprendre et familier à de nombreux développeurs
  • Extensibilité
    • TypeSpec peut être étendu grâce à un vocabulaire de décorateurs personnalisés et à des templates de type, permettant de modéliser des API dans des domaines de logique métier ou applicative
  • Écosystème
    • Avec TypeSpec, il est possible d’emballer des types communs, des extensions de langage, des linters et des émetteurs dans des packages à distribuer sur npm au sein d’une organisation ou d’un écosystème

Communauté et collaboration

  • Utilisé chez Microsoft
    • Microsoft utilise TypeSpec pour transformer son processus de développement d’API
    • Beaucoup de services Azure l’adoptent, et leur nombre augmente chaque jour
    • L’équipe Microsoft Graph s’appuie sur le potentiel de TypeSpec pour augmenter la productivité et simplifier la personnalisation
  • Appel à participation
    • TypeSpec est plus qu’un simple langage : c’est une communauté
    • Tous les profils de développeurs sont invités à participer à la bêta publique afin de constater eux-mêmes la puissance de TypeSpec

Avis de GN⁺

  • TypeSpec apparaît comme un langage de définition d’API à haut niveau d’abstraction, pouvant améliorer de manière révolutionnaire la manière de développer des API
    • En prenant en charge l’approche « API First », il devrait aider à améliorer l’efficacité du développement et la qualité du produit final
    • Grâce à sa prise en charge de nombreux protocoles, à son extensibilité et à son écosystème solide, il devrait être applicable à un large éventail de scénarios de développement
  • Toutefois, l’introduction d’un nouveau langage entraîne toujours des coûts d’apprentissage, donc une formation suffisante devrait précéder son adoption en interne
    • Le choix de s’inspirer de la syntaxe de TypeScript et de C# pour réduire la courbe d’apprentissage est positif
  • Les points de différenciation avec les langages de définition d’API existants (Swagger, RAML, API Blueprint, etc.) qui remplissent un rôle similaire gagneraient à être clarifiés davantage
    • Il serait utile de préciser comment il surmonte les limites des langages existants, la facilité de migration, etc.
  • La stratégie de dogfooding menée en premier au sein de Microsoft inspire confiance
    • Mais comme le projet n’a été publié en open source que récemment, son évolution continue et le support communautaire seront décisifs dans les prochaines années
  • La direction visant à améliorer la standardisation et la réutilisabilité de la conception d’API est pertinente, mais donne aussi l’impression de vouloir résoudre trop de choses à la fois
    • Il serait préférable de renforcer progressivement les fonctionnalités par priorisation

À lire aussi

1 commentaires

 
GN⁺ 2024-05-02
Avis sur Hacker News

  • Il existe déjà des types TypeScript pour les API, donc j’ai créé https://github.com/vega/ts-json-schema-generator pour générer directement des schémas JSON depuis les sources
    Les ensembles de fonctionnalités des deux langages diffèrent un peu, ce qui crée quelques bizarreries, mais je l’utilise avec succès depuis des années. Si vous n’avez pas TypeScript, ou si la surface de votre API est assez petite pour que réécrire les types ne soit pas un problème, TypeSpec vaut aussi le coup d’œil. C’est clairement mieux que d’écrire des schémas JSON à la main

  • À côté du YAML d’OpenAPI, n’importe quoi a l’air bien, donc ça paraît un peu déloyal. Cela dit, je pense toujours qu’OpenAPI reste l’une des meilleures évolutions
    D’un autre côté, j’ai longtemps espéré que TypeScript s’impose comme langage de schéma. Plus précisément, son sous-ensemble non impératif et non fonctionnel, étonnamment vaste. À première vue, cela ressemble assez à : « et si on retirait JavaScript de TypeScript pour ne garder que les types destinés au JSON, puis qu’on ajoutait une description des métadonnées d’endpoints afin d’en faire le successeur pratique d’OpenAPI et de WSDL ? »

    • « À côté du YAML d’OpenAPI, n’importe quoi a l’air bien » : je relève le défi
      https://github.com/bufbuild/protovalidate/blob/main/examples...
    • Le système de types de TypeScript est très avancé ; il me semble donc impossible de créer des bindings pour tous les grands langages tout en restant idiomatique dans chacun d’eux. Un langage d’API gagne à être très simple et direct

  • J’utilise TypeSpec récemment pour des API, et je cherchais un outil permettant de décrire une API comme GraphQL tout en adoptant une approche design-first
    Les éditeurs OpenAPI sont tous trop lourds, et les relations entre les données au sein de l’API n’y apparaissent pas clairement. TypeSpec correspondait exactement à ce que je cherchais, et il m’a vraiment aidé sur ce point

  • Microsoft dit croire à la valeur du « dogfooding », c’est-à-dire utiliser ses propres produits, mais quand on regarde l’écosystème chaotique du développement desktop natif Windows ou l’adoption de Xamarin/MAUI pour les apps mobiles, ce n’est pas vraiment l’impression que ça donne

    • Windows fait du dogfooding de toutes les options de développement d’apps natives en même temps
    • Le dogfooding ne veut pas dire tout réécrire de zéro à chaque nouvelle technologie
    • C’est peut-être une nouvelle politique, ou bien quelque chose qui ne s’applique qu’à ce produit parce que c’est plus facile à vendre marketinguement
      J’ai essayé de gérer des e-mails avec Microsoft Graph ; si Outlook l’utilise, je serais assez surpris

  • Comme cela vient de Microsoft, ça ressemble à une réponse à GraphQL. S’ils l’utilisent vraiment en interne, la qualité de l’outillage pourrait être correcte, peut-être meilleure que quelque chose assemblé à la hâte par un consortium open source
    Je n’en suis pas encore convaincu, mais ça semble pouvoir attirer davantage d’attention

    • Je travaille dans l’équipe, et il est difficile de considérer TypeSpec comme équivalent à GraphQL ; c’est aussi pour cela que TypeSpec seul ne peut pas vraiment occuper cette place
      GraphQL repose sur beaucoup de présupposés forts nécessaires pour bâtir des applications concrètes : protocole, gestion des erreurs, sémantique des requêtes, etc. À l’inverse, le cœur de TypeSpec ressemble plutôt à un DSL sans présupposés pour décrire des API. Les bindings vers des protocoles spécifiques sont ajoutés sous forme de bibliothèques, et une bibliothèque GraphQL fait depuis longtemps partie des pistes envisagées
      En résumé, si Microsoft créait un ensemble de présupposés permettant de résoudre des scénarios similaires à GraphQL, TypeSpec pourrait servir de langage de description d’API dans ce contexte. Mais il ne faut pas assimiler ces présupposés à TypeSpec lui-même

  • Je n’ai pas trouvé la question centrale : les langages de sortie pris en charge. Est-ce qu’on est obligé d’exporter vers OpenAPI puis d’utiliser l’un de ses horribles générateurs ?

    • On peut créer son propre émetteur, et la documentation explique comment faire. Notre équipe a créé un émetteur personnalisé pour TypeSpec afin de produire un ensemble de SDK et de bibliothèques

  • Ça ressemble à une version TypeScript de WSDL
    https://en.wikipedia.org/wiki/Web_Services_Description_Langu...
    Est-ce que ça survivra plus longtemps que WSDL ?

    • On utilise encore WSDL, ou plus précisément la plateforme sur laquelle je travaille l’utilise. Ce n’est peut-être plus populaire pour les nouvelles technos, mais c’est toujours vivant. Vous pouvez le critiquer, mais du XML généré reste préférable à du YAML généré
    • Vous le savez peut-être déjà, mais l’analogie la plus précise serait plutôt WSDL+SOAP
      WSDL et SOAP sont définis en XML, et SOAP décrit du XML. La popularité de ces technologies a suivi la montée puis le déclin de la popularité générale de XML. TypeSpec décrit JSON et protobuf ; si ces formats perdent en popularité, TypeSpec risque fortement d’en perdre aussi
    • Le problème de WSDL, c’est qu’il a été conçu par plusieurs comités de grandes entreprises. Il était donc incohérent et obèse. C’était aussi le cas de beaucoup de standards liés à XML
      Aujourd’hui, les grandes entreprises préfèrent lancer leur propre solution sur le marché pour prendre des parts plutôt que travailler ensemble. Résultat : une équipe se concentre sur un objectif unique, ce qui peut donner une approche de meilleure qualité. C’est mieux que d’essayer de satisfaire 10 fournisseurs ayant chacun leur propre agenda

  • Ce serait bien de pouvoir simplement importer un fichier TypeSpec depuis TypeScript ou un autre langage et obtenir automatiquement des types TypeScript
    La génération de code est pénible et sujette aux erreurs

    • En général, je préfère la génération de code. Je ne vois pas pourquoi elle serait plus sujette aux erreurs que les autres approches
      Au contraire, cela peut faciliter le débogage, car les erreurs ne sont pas cachées derrière deux couches d’abstraction. Le code généré permet aussi d’ajouter une étape de build pour contourner des lacunes ou des bugs du générateur ; avec une autre approche, on doit souvent les subir tels quels
      Je comprends l’aspect « pénible ». Un retour immédiat est évidemment préférable au fait de relancer un build ; dans les zones où l’on itère beaucoup, l’avantage de l’approche opposée devient donc important
    • Ça ressemble aussi beaucoup à TypeScript. Pourquoi ne pas utiliser TypeScript dès le départ pour la description d’API ? On obtiendrait des types TypeScript, et on pourrait générer à la volée le schéma OpenAPI à exposer sur /openapi

  • Est-ce que ça pourrait convertir du YAML pour la chaîne d’outils souhaitée ?
    Comme le faisait CORBA IDL il y a 25 ans, ce serait appréciable d’avoir un IDL de haut niveau qui génère des schémas et des stubs pour plusieurs langages

    • Il y a quelques jours, j’ai ajouté à mon générateur de code basé sur OpenAPI 3 la prise en charge de TypeSpec comme spécification d’entrée
      Ça a été assez simple, car il fournit une API pour convertir en document OpenAPI (https://github.com/mnahkies/openapi-code-generator/pull/158)
      Je me concentre à la fois sur la génération de SDK clients et de stubs serveur, mais pour l’instant seul TypeScript est pris en charge. Quand je serai satisfait de la maturité des templates TypeScript, j’aimerais ajouter d’autres langages un jour
    • Les émetteurs OpenAPI et JSON Schema peuvent produire du YAML

  • Un langage dédié est difficile à vendre, et cela demande aussi un effort supplémentaire considérable à l’équipe qui le crée
    Les gens n’ont pas envie d’apprendre un langage dédié. Il faut aussi construire tout l’outillage d’écosystème de langage : compilateur, documentation, language server, intégration IDE, gestion des dépendances, etc.
    WaspLang et DarkLang sont des tentatives similaires, mais je ne les ai pas encore vus utilisés de façon significative dans la pratique ou sur HN. Mieux vaut utiliser un langage existant et se concentrer sur la valeur ajoutée
    Personnellement, j’ai aussi travaillé sur quelque chose à valeur similaire, à savoir « source de vérité -> tout », et j’ai connu une partie de ces douleurs
    https://github.com/hofstadter-io/hof
    L’idée, c’est CUE + text/template = un outil de génération qui ne se limite pas aux API

    • C’est soit utiliser ça, soit écrire directement du YAML OpenAPI. Même pour quelqu’un qui connaît YAML, définir et utiliser une définition OpenAPI de base avec ceci est beaucoup plus simple que rédiger à la main un document OpenAPI. Le faire à la main est vraiment pénible
    • Avec l’essor de la programmation par IA générative, les nouveaux langages partent avec un handicap encore plus important. Même un nouveau framework objectivement meilleur peut entraîner une productivité réelle plus faible si l’IA ne l’a pas appris
    • Merci pour hof. J’envisage de l’utiliser sur un projet. Quel est l’état actuel du projet ? Comme les commits récents semblent avoir diminué, je me demande s’il est aujourd’hui stable et utilisable tel quel