TypeSpec: A new language for API-centric development

lol, about 5 years too late. I've been developing REST APIs with Ballerina for some time now and there's a multitude of quality of life improvements for me. Look at this https://ballerina.io/learn/write-a-restful-api-with-ballerin...

I guess it's NIH for Microsoft. Oh well, at least it's TypeScript.

Smithy is _very_ similar to Coral (an internal library within Amazon).

Coral is used by every AWS service -- every AWS service defines their APIs using Coral, and if you want to interact with another service you use a generated client.

The client can generally be used as-is, though sometimes you might want some custom client code. In the case of a generated client you can just grab the API definition of the API you want to call, generate the client in the language of your choice, and... that's it!

For the server, you still have to implement the logic of how to form the responses, but what the request/responses look like it enforced by the framework.

Here's an example: https://gist.github.com/shepherdjerred/cb041ccc2b8864276e9b1...

I'm leaving out a _lot_ of details. Coral is incredibly powerful and can do a lot of things for you for free. Smithy is, from what I can see, the same idea.

The toy example with an API definition that includes zero semantic documentation doesn’t give me a lot of confidence that TypeSpec helps author API definitions that are actually good. It’s easy to create a concise language if all you want to generate is boilerplate.

it doesn't look worse than OpenAPI's yaml to me

it's fairly concise, the method and the request/response types are well separated and readable

the only thing I could argue with is mixing validation and type defs, as it looks like one of these things that quickly evolve over time and you end up duplicating both in the schema and the business logic

The solutions you are talking about are called "code-first", TypeSpec is a "schema-first" solution. Both solutions have their pros and cons:

Code-first:

- No extra steps between code and running application

- No mismatch between schema and code

- Requires tooling for every language used in your stack. This tooling is usually more complex than schema-first codegen, but it is almost always built-into and core of the backend framework you are using so it tends to be better supported.

- Requires teams to know each service's backend language to propose changes

- Harder to build a coherent central API documentation if you have multiple services. Requires complex tooling for merging the different schemas from the different services

Schema first:

- Schema first means contract-first design, scales better to products with multiple separate teams using multiple languages. It is easier to learn the schema DSL than poke around backend language unknown to the developer

- Any change in the contract requires changes in two places (schema and code)

- API consumers can easily suggest changes to the schema that are implemented by the relevant team

- Usually requires some codegen step for each backend and client languages (with the usual codegen problems). Runtime-only schema validation can be done but it is usually a bad idea to rely only on it.

- Easier mocking. Clients can start implementing before backend is ready, tests can be written against mocks.

There are definitely more pros and cons that I am missing, but it is a tradeoff. I would say if you have multiple backend services and supporting multiple backend languages I would definitely go for schema-first.

You can work with OpenAPI in a schema-first way but as many people have pointed out over the years OpenAPI yaml files are, to be polite, not very human-friendly. TypeSpec seems to be a more sensible way to work with HTTP apis in a schema first way while keep interoperability with existing OpenAPI tooling at the cost of extra codegen step (typespec .tps -> openapi .yaml)