Microsoft TypeSpec

[9dev]

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.

[bterlson]

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.

I explained a bit more here last time TypeSpec was on here: https://news.ycombinator.com/item?id=39843184

[sixhobbits]

https://www.speakeasy.com/guides/api-frameworks/typespec

This post has a bit more detail about why "we don't need more standards" might not be the correct take here

(Disclaimer speakeasy is a client but I wasn't directly involved in writing this and just figured it's pretty relevant here)

[thrance]

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.

[crowdyriver]

It's even worse, you still need node to run this thing, so you don't avoid the node dependency.

[pc86]

You don't get a bonus and promotion for just using TypeScript.

[wg0]

"Looks good on my CV" syndrome.

[recursivedoubts]

> Create a new TypeSpec project

> 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.

[morbicer]

You can be technically correct or you can move on and accept that terminology means what majority of people mean.

https://learningenglishwithoxford.com/2024/02/29/15-modern-e...

[Alupis]

Eagerly awaiting AsyncAPI Support: https://github.com/microsoft/typespec/issues/2463

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%.

[bananaquant]

As someone mostly using compiled programming languages, I am perplexed about the built-in types that this new language provides.

According to https://typespec.io/docs/standard-library/built-in-data-type...:

* unixTimestamp32, but no 64-bit version

* plainDate that can be "April 10th" without the year

* DefaultKeyVisibility, OmitDefaults.. what?

I am genuinely curious how did that happen. Design by committee? Some secret use cases that leaked into specification?

[meindnoch]

How many times have we invented this particular wheel already?

[otabdeveloper4]

OpenAPI (formerly known as Swagger) is the actual standard in this problem space.

It's good enough and these bespoke solutions that add nothing but DSL syntactic sugar are dead on arrival.

[agentultra]

https://www.servant.dev/

It’s an evergreen project. I’ve seen various incarnations of this since the 90s.

[whynotmaybe]

The xkcd about "standards" is from 2011, so a lot ? https://xkcd.com/927/

[coreyh14444]

This came up a few months ago here: https://news.ycombinator.com/item?id=40206124

[kingkongjaffa]

If I’m a lowly nerdling writing a backend in express and typescript, what do I use this for?

[ActionHank]

Generating client code to query your apis with function calls. Mostly useful when you have more than one client codebase.

[Alupis]

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.

[gjmveloso]

It’s a lot of language for a DSL to define services. Smithy[1] sounds more balanced and extendable

[1]: https://smithy.io/2.0/index.html

[unshavedyak]

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.

[Alupis]

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.

[drewda]

Originally this project also advertised support for GraphQL, but never implemented it: https://github.com/microsoft/typespec/issues/1390

Would be compelling to have a way to represent both OpenAPI and GraphQL in a common upstream schema...

[bterlson]

It is being worked on. The best place to follow the development is our discord, there's a channel for graphql.

[ChrisArchitect]

Related April 2024:

Introducing TypeSpec: A New Language for API-Centric Development

https://typespec.io/blog/2024-04-25-introducing

(https://news.ycombinator.com/item?id=40206124)

[henning]

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.

[outlore]

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.

[miohtama]

Now, let me tell you about microservices... (:

[activitypea]

The syntax leaves a bad first impression. I'm getting flashbacks to Java EE/JAX-RS days.

[andremedeiros]

What does this do that Protobuf doesn't?

[codeflo]

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).

[frankfrank13]

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).

[bterlson]

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.

[afavour]

> TypeSpec's standard library includes support for OpenAPI 3.0, JSON Schema 2020-12 and Protobuf.

[davedx]

Protobuf is a binary spec isn’t it?

[jjkaczor]

Microsoft NIHS (not-invented-here-syndrome)

[miohtama]

Looks nice!

Any recommendations for Python backend integration?

[that70sshow]

why should one use this if both thrift and protobuf solves 90% of the needs.

[mdaniel]

> list(@query filter: string): Store[];

I despise "hidden" languages smuggled in string types. Both Microsoft <https://learn.microsoft.com/en-us/graph/filter-query-paramet...> and Google <https://google.aip.dev/160> are terrible about these embedded languages

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