I just don’t get why they absolutely had to come up with new syntax. All of this would have been possible with standard Typescript, unlocking heaps of existing tooling, editor support, and prior knowledge. But no! Let’s come up with a new language, bespoke compiler, new LSP and IDE integrations, and make developers learn yet a new DSL.
It’s creating changes for the sake of creating changes.
We first tried a TypeScript DSL and I really wish it would have worked for our use cases (e.g. describing complex REST APIs in Azure), but unfortunately it didn't.
Having your Framework generate the Docs is nice, but doesn't always fit.
At work, I build backends for mobile applications. When designing new APIs to be consumed by apps, we want input from the mobile developers. We facilitate this by having an api-specs repo with TSP and using Pull Requests to discuss, track and finally commit on new APIs.
It also allows mobile developers to open PRs with changes they want. The contracts are basically an interface that both sides can discuss and agree on.
Came here to post this. We use Django Ninja at work (basically FastAPI style endpoints for Django), and it automatically does OpenAPI and Swagger docs for us. Whatever web framework one chooses in whichver language should def have this built-in by now, IMO, seems like tablestakes for anything larger than a "micro-framework"
Off the top of my head, I don't think you can perfectly describe the type (string format) of an UUID in typescript types, which you can do with OpenAPI. That may be a reason.
You can get by, e.g. you can use JSDoc comments describing format or pattern, generic types taking a parameter of either format or pattern along with a base type, or create a custom well-known type you define as having the properties of a UUID. But aside from comments, this is not reflected well in the tooling, and none of these options compose particularly well.
I'm not sure why you're getting downvoted. It might be hitting too close to home for some. But yeah, 95% of developers choose things to do to boost them for the next job.
I believe that 99% of the time, a reuse of older technologies results in greater innovation that is more stable and a return is multiple of the underlying foundations.
This applies here as well. Typescript could go a long way.
But admittedly, writing a grammar, parser and then a whole compiler along with its tooling of a new DSL is fun for sure but does look good on CV as well.
I downvoted both of your comments because I think it's rude and insulting to assume the motivation of someone's work is self-aggrandizing, and to dismiss out of hand the work might be motivated by technical needs because you can't immediately recognize those needs. I find the attitude frustrating, similar to the other common HN dismissal of "I could build it in a weekend".
> Run the following command in a clean directory to create a new TypeSpec project.
> tsp init
> This will prompt you with a few questions. Pick the Generic REST API template...
I’d just like to interject for a moment. What you’re referring to as REST, is, in fact, JSON/RPC, or as I’ve recently taken to calling it, JSON plus RPC. JSON is not a hypermedia unto itself, but rather a simple data format made useful by out of band information often specified with tools such as your TypeSpec project or similar.
Many computer users work with a canonical version of REST every day, without realizing it. Through a peculiar turn of events, the version of REST which is widely used today is often called “The Web”, and many of its users are not aware that it is basically the REST-ful architecture, defined by Roy Fielding.
There really is a REST, and these people are using it, but it is just a part of The Web they use. REST is the network architecture: hypermedia encodes the state of resources for hypermedia clients. JSON is an essential part of Single Page Applications, but is useless by itself; it can only function in the context of a complete API specification. JSON is normally used in combination with SPA libraries: the whole system is basically RPC with JSON added, or JSON/RPC. All these so-called “REST-ful” APIs are really JSON plus RPC.
AsyncAPI support would make TypeSpec the end-all/be-all API spec tool for a lot of people.
TypeSpec looks amazing - but until we can go "all in" on using it for both our external and internal API, it's difficult for the team to justify yet another new DSL. It's needs to support all of our common API definition woes, and currently it only addresses 50%.
This is part of the Api-First paradigm. Instead of your controllers/handlers being the authoritative "Truth", the API spec is.
You and your team spend time arguing/debating the API from the perspective of a user. "I need X data from Y service", etc. The document then becomes the "blueprint" for your system.
Think of it as TDD but viewed from a different angle. In a microservices system, this has a tremendous amount of advantages, including being able to codegen your handlers and models, maintain consistency across the entire API, unified api documentation, increase testability of your controller/handler interface, and more.
Is there a good UI for this? I want to love OpenAPI but for complex JSON i've found OpenAPI UI's to be unusable. At this point i'd hand write my API specifications if it meant i could have a useful UI.
TypeSpec is a specification document generator - it outputs OpenAPI specification files, which you can feed to any OpenAPI documentation generator, such as Swagger or Redocly.
Oh, so if I want to add a simple checkbox boolean field on a model on a proper best practices Clean Code Uncle Bob-approved code base in 2024, I have to:
- add it in the database model
- make a database migration for the field
- add it in the DTO for the API because we don't want to couple our persistence layer to our business logic or something
- add it to gRPC/Protobuf models so other services can call it
- add it to the new TypeSpec model thing
- update tests of all of the above
I love in tech 2024, it's full of people who talk about "DRY" who force you to repeat the same things over and over again, and this is "clean code", and if you don't like it, fuck you, you aren't a "culture fit". Utterly batshit insane.
I understand your frustration, but this is the price paid for schema compliance across systems.
One qualification: the TypeSpec model should help generate your API DTOs (OpenAPI, Protobuf) etc. So hopefully that saves a step or two.
As an aside, I have tried doing a full stack TypeScript application where database types trickle down to the client, it ended poorly, since the API affordances can and should evolve separately from the database design. Therefore, I do feel that separation of database and API types is necessary.
Unions, generics, required fields, default values, enums that don't pollute the global namespace are things that immediately caught my eye. I assume it also doesn't repeat Protobuf's the mistake of not being able to distinguish between a missing string value and an empty string value.
Protobuf is old, and has some really strange warts that are only explainable historically (for example, by reference to the behavior of C++, which used to be Protobuf's primary target).
I have long used protobuf as the source of truth for API's, but it does have some weird idiosyncrasies since its primarily a binary spec, and doesn't always transfer to json well (e.g optionals, maps, etc).
As someone who works on TypeSpec, my feeling is that they are mostly different things. TypeSpec is a general purpose DSL which supports "emitting" to protobuf and other things, but in and of itself doesn't prescribe any particular protocol or serialization format.
Gotcha. I think this might be where Protobuf falls short because you have to "source" the tooling for all its different outputs, but support for OpenAPI 3.0 spec generation has existed for over a year.
Superior in performance and easy-of-use, which for most people is all that matters. Atom still won in general "hackability", which was one of its main selling points. Unfortunately that didn't stick, and the kind of people that want a hackable-to-the-core editor are probably using Emacs. I know I am.
TypeScript wasn't better than Flow when it gained dominance. It happened because Microsoft created an out-of-the-box experience with VS Code that worked great with TypeScript but made Flow types look broken.
More generally Microsoft treated Typescript as a product - they built it based on feedback from outside users and worked hard to make it easily adoptable and to grow a community around it. They are also "pragmatic" - willing to have weird, unsound semantics if it's needed to help people adopt Typescript and model existing JS ecosystem patterns.
Flow has always been an inwardly-focused project that is for Facebook's needs first. The Flow team at FB made an explicit decision to focus more on compiler performance improvements (what Facebook's usage needed) over outside users & community.
The way I remember, when flow was introduced, you had to do small changes to 3rd party dependencies your code might have had to make them flow-compatible.
With typescript you could just write a type definition file for any 3rd party library, so you could essentially make any 3rd party dependency "typescript compatible" without needing to change its code.
This small difference made a huge impact for adoption. Eventually flow also got that feature but by then the adoption difference was already too big.
From what I remember TypeScript was a superset of Javascript, so you could just rename your files and enable TypeScript and it all worked, and then gradually move stuff over. That probably helped a lot.
It was released. It was on a growing number of webpages and an important part of the Dev Tools of IE9+ (also giving them a massive install base from before Atom existed). If Atom didn't build Electron what became the VS Code team might have built something similar on their own eventually (though it probably would have been IE-based and Windows-only in that alternate history). It truly seemed convergent evolution at work.
Since Microsoft is one of the offenders, how about any novel type system try and model their own API and only when that's possible should they taut their superiority over the existing, proven standards
How often are people hand-writing OpenAPI specs? At least in my experience, such specs are generated from some "authoritative" implementation. This looks like it aims to move the contract-y bits into something less verbose than OpenAPI and less tied to a specific implementation.
I did. I cannot recommend this approach - you often gain little for a lot of pain for editing Yaml. Better just use DSL in your backend language and generate the spec.
Hand writing OpenAPI is horrible in my experience. Maybe it's particularly bad because we have a lot of small types that are nested into each other and get composed together a lot, but at the end of the day our OpenAPI YAML needs to be about 1.2MB and I just can't see maintaining that by hand in a text editor.
Handwriting OpenAPI for a bunch of REST APIs will destroy both your keyboard and your sanity. Prefer writing good old x86 assembly over OpenAPI specs. The OpenAPI folks designed the most verbose spec language possible. I guess they took inspiration from Cobol.
Isn't OpenAPI specific to REST? The page also mentions protobuf, for example. Being able to generate clients and servers for those things might be useful, although how well it integrates with the client/server technologies will be the hard bit.
Agreed, OpenAPI is battle tested and has all the tooling I could ever dream of and then some. It doesn't matter who needs to consume it, there's tools for any and every language.
It’s creating changes for the sake of creating changes.