- TypeSpec es un nuevo lenguaje para el desarrollo centrado en APIs, diseñado para satisfacer las necesidades de desarrolladores, diseñadores y gerentes de APIs
- Fue desarrollado en un entorno en el que ofrecer APIs de alta calidad y experiencias relacionadas de manera consistente se vuelve cada vez más compleja y crítica
- TypeSpec es más que un lenguaje; es una plataforma que habilita la abstracción, fomenta la reutilización de código y aprovecha herramientas modernas para un desarrollo ágil
Características principales de TypeSpec
- Interoperabilidad
- TypeSpec no es un lenguaje de descripción de API simple, sino un lenguaje de definición de alto nivel que permite definir APIs y generar al mismo tiempo múltiples protocolos, clientes, servidores y documentación
- Es interoperable con los lenguajes de definición de API estándar de la industria, reduciendo la brecha entre distintas opciones
- Productividad
- TypeSpec ofrece una excelente experiencia de desarrollador para hacer que la definición de datos y APIs sea más agradable y productiva
- El lenguaje es conciso y permite definir datos y formas complejas de API con una entrada mínima
- Patrones de API
- TypeSpec encapsula tipos de datos comunes, patrones de API y guías en componentes reutilizables de alto nivel que pueden compartirse en todo el equipo o el ecosistema, mejorando así la calidad de las API
- Familiaridad
- Inspirado en TypeScript y C#, TypeSpec es fácil de aprender y se siente familiar para muchos desarrolladores
- Extensibilidad
- TypeSpec puede ampliarse con vocabularios de decoradores personalizados y plantillas de tipos, lo que permite modelar APIs en dominios de lógica de negocio o lógica de aplicación
- Ecosistema
- Con TypeSpec, puedes empaquetar tipos comunes, extensiones de lenguaje, linters y emitters para distribuirlos en NPM dentro de la organización o en todo el ecosistema
Comunidad y colaboración
- Uso en Microsoft
- Microsoft está transformando su proceso de desarrollo de API con TypeSpec
- Muchos servicios de Azure lo han adoptado y su número aumenta todos los días
- El equipo de Microsoft Graph está aprovechando el potencial de TypeSpec para aumentar la productividad y simplificar la personalización
- Invitación a participar
- TypeSpec es más que un lenguaje: es una comunidad
- Invita a desarrolladores de cualquier perfil a unirse a la beta pública y experimentar personalmente el poder de TypeSpec
Opinión de GN⁺
- TypeSpec parece un lenguaje de definición de API con un alto nivel de abstracción que podría mejorar de forma innovadora la forma de desarrollar APIs
- Al soportar un enfoque "API First", debería ayudar a mejorar la eficiencia de desarrollo y la calidad final del producto
- Se espera que sea aplicable a una amplia gama de escenarios de desarrollo gracias a su soporte para múltiples protocolos, extensibilidad y un ecosistema robusto
- Sin embargo, la adopción de un lenguaje nuevo siempre implica costos de aprendizaje, por lo que antes de introducirlo en un equipo debería haber capacitación suficiente
- Es positivo el esfuerzo por reducir la curva de aprendizaje al tomar prestadas la sintaxis de TypeScript y C#
- Parece necesario aclarar con más nitidez los puntos de diferenciación frente a otros lenguajes de definición de API existentes (Swagger, RAML, API Blueprint, entre otros)
- Cómo supera las limitaciones de los lenguajes existentes, si la migración es sencilla, etc.
- El enfoque de dogfooding de usarlo primero dentro de Microsoft y mejorarlo a medida que avanza genera confianza
- Pero como todavía se publicó hace poco como proyecto de código abierto, su evolución sostenida y el apoyo de la comunidad durante los próximos años serán cruciales
- La dirección de estandarizar el diseño de API y mejorar su reutilización es correcta, aunque también da la impresión de querer resolver demasiadas cosas al mismo tiempo
- Sería recomendable priorizar y fortalecer gradualmente las funcionalidades
1 comentarios
Comentarios en Hacker News
Ya había tipos de TypeScript para APIs, así que hice https://github.com/vega/ts-json-schema-generator, que genera esquemas JSON directamente desde el código fuente
Los conjuntos de funciones de ambos lenguajes difieren un poco, así que hay partes raras, pero lo he usado bien durante años. Si no tienes TypeScript o el área superficial de la API es pequeña y no pasa nada por volver a escribir los tipos, TypeSpec también vale la pena mirar. Definitivamente es mejor que escribir esquemas JSON a mano
Al ponerlo al lado del YAML de OpenAPI, cualquier cosa se ve bien, así que se siente un poco como hacer trampa. Aun así, sigo pensando que OpenAPI fue uno de los mejores cambios
Por otro lado, desde hace tiempo he esperado bastante que TypeScript se establezca como lenguaje de esquemas. Más exactamente, ese subconjunto no imperativo ni funcional sorprendentemente grande. Mi primera impresión es más o menos: “¿y si a TypeScript le quitamos JavaScript para dejar solo tipos para JSON, y le agregamos descripciones de metadatos de endpoints para que sea el sucesor de facto de OpenAPI y WSDL?”
https://github.com/bufbuild/protovalidate/blob/main/examples...
Últimamente estoy usando TypeSpec para APIs, y estaba buscando una herramienta que permitiera describir una API como GraphQL, pero con un enfoque de design-first
Todos los editores de OpenAPI me parecían demasiado torpes, y no mostraban bien las relaciones de datos dentro de la API. TypeSpec fue exactamente la herramienta que estaba buscando y de verdad me ayudó aquí
Microsoft dice creer en el valor de hacer “dogfooding” con sus propios productos, pero viendo el caótico ecosistema del desarrollo nativo de escritorio en Windows o la adopción de Xamarin/MAUI en apps móviles, no parece tanto así
He probado gestionar correo con Microsoft Graph, y me sorprendería bastante si Outlook realmente usara eso
Como viene de Microsoft, parece una respuesta a GraphQL. Si lo usan internamente como dogfooding, la calidad de las herramientas podría ser al menos razonable comparada con algo improvisado por un consorcio open source
Todavía no estoy convencido, pero parece que podría atraer más atención
GraphQL trae muchas suposiciones fuertes necesarias para construir una aplicación concreta: protocolo, manejo de errores, semántica de consultas, etc. En cambio, el núcleo de TypeSpec se parece más a un DSL sin suposiciones para describir APIs. Los bindings a protocolos específicos se agregan como bibliotecas, y una biblioteca para GraphQL es algo que evaluamos desde hace mucho
En resumen, si Microsoft crea un paquete de suposiciones para resolver escenarios parecidos a GraphQL, en ese contexto sí se podría usar TypeSpec como lenguaje de descripción de APIs. Pero no sería correcto equiparar esas suposiciones con TypeSpec en sí
No pude encontrar la pregunta clave: los lenguajes de salida compatibles. ¿La única opción es exportarlo a OpenAPI y luego usar uno de esos horribles generadores de ese lado?
Parece una versión de WSDL en TypeScript
https://en.wikipedia.org/wiki/Web_Services_Description_Langu...
¿Durará más que WSDL?
WSDL y SOAP se definen en XML, y SOAP describe XML. La popularidad de estas tecnologías subió y bajó junto con la popularidad general de XML. Como TypeSpec describe JSON y protobuf, si esos formatos pierden popularidad, TypeSpec probablemente también la perderá
Hoy las grandes empresas prefieren lanzar su propia solución al mercado para ganar espacio, en vez de trabajar juntas. Como resultado, a veces aparecen enfoques de mejor calidad porque un solo equipo se concentra en un objetivo único. Es mejor que tratar de satisfacer a 10 proveedores distintos, cada uno con su propia agenda
Estaría bueno poder importar un archivo de TypeSpec directamente desde TypeScript u otro lenguaje y obtener automáticamente tipos de TypeScript
La generación de código es engorrosa y propensa a errores
De hecho, puede ser más fácil de depurar porque los errores no quedan escondidos detrás de dos capas de abstracción. Con código generado puedes incluso agregar un paso de build para rodear limitaciones o bugs del generador, mientras que con otros enfoques muchas veces solo te toca aguantarlos
Sí entiendo la parte de que “es engorroso”. La retroalimentación inmediata obviamente es mejor que volver a correr el build, así que en áreas donde haces muchos cambios iterativos, la otra opción también tiene ventajas importantes
/openapi¿Se podrá transformar a YAML para la cadena de herramientas que uno quiera?
Como hacía CORBA IDL hace 25 años, estaría bueno contar con un IDL de alto nivel que genere esquemas y stubs para varios lenguajes
Como ofrece una API para convertirlo a documentación OpenAPI, fue bastante sencillo (https://github.com/mnahkies/openapi-code-generator/pull/158)
Estoy enfocado en generar tanto SDKs de cliente como stubs de servidor, pero por ahora solo soporta TypeScript. Si quedo satisfecho con el nivel de madurez de las plantillas de TypeScript, me gustaría agregar otros lenguajes algún día
Es difícil convencer a la gente de usar un lenguaje dedicado, y además implica bastante trabajo extra para el equipo que lo crea
La gente no quiere aprender un lenguaje dedicado. Además, hay que construir todo el ecosistema de herramientas del lenguaje, como compilador, documentación, servidor de lenguaje, integración con IDE y gestión de dependencias
Hay intentos parecidos como WaspLang y DarkLang, pero todavía no los he visto usarse de forma significativa ni en entornos reales ni en HN. Es mejor usar lenguajes existentes y concentrarse en el valor agregado
En lo personal también he trabajado en algo con una idea similar, eso de “fuente única de verdad -> todo”, y he sufrido parte de ese dolor
https://github.com/hofstadter-io/hof
La idea es CUE + text/template = una herramienta de generación no limitada a APIs