71–80 of 121 posts
> At Microsoft, we believe in the value of using our own products, a practice often referred to as "dogfooding". One would think, unfortunely that is not how it looks like in the zoo of native Windows desktop development, or Xamarin/MAUI adoption in their mobile apps.
What is wrong with protobufs and grpc?
Spec api code, imo. Feels like it's going backwards - there's really no reason why it has to be a .tsp, instead of a .ts with actual api code. It's even using @annotations. In fact the annotations i see in the screenshot (@route, @query, @path) are practically the same in NestJS. I feel that we should be focusing on enhancing that paradigm instead. In fact I already have a working POC of NestJS -> OpenAPI -> Client l…
Not to mention, how else do you see what complex logic might happen in an endpoint?
It seems typespec deals only with extremely simple CRUD APIs, for which again just reading the code would be good enough.
In scenarios where you want to offer the API consuming team some mock, I'd argue time would be better spent providing them with a a json-server implementation (see: https://www.npmjs.com/package/json-server).
Spec api code, imo. Feels like it's going backwards - there's really no reason why it has to be a .tsp, instead of a .ts with actual api code. It's even using @annotations. In fact the annotations i see in the screenshot (@route, @query, @path) are practically the same in NestJS. I feel that we should be focusing on enhancing that paradigm instead. In fact I already have a working POC of NestJS -> OpenAPI -> Client l…
Spec-first approach works better when client and server teams work on their parts simultaneously and need some contract before the implementation starts.
If it does become a long lived artifact, CI/CD must also be a nightmare, having to figure out which commit matches which version of the specification, since the spec is now a distinct artifact from it's documented target, and similar which version of the client. A literal "3 body problem".
On the other hand, if you already have a project template (granted, you do need to fight through all of the various build-time configuration required to get a typescript project up and running) you could probably achieve the same by simply stubbing the API endpoints in code to generate the spec.
If there was an advantage to a spec first model, it would be that any change to the api would be a conscious change, and highly visible. I've also encountered situations where a innocuous refactor (changing a class name or method name) broke the previous builds. But one could potentially integrate a gate into CI/CD by diffing the outputs of generated specs.
Much of my opinion on this subject is based on my own experience using Postman as a pre-implementation spec. But conceptually I see the same problems arising from any spec-first approaches.
Earlier quoted context omitted.
What if you need to generate two server implementations (possibly in different languages) that adhere to the same specification? You don’t always go server -> spec -> client.
That seems like a rare use case. Surely we optimise for the general use case - you start working on a new server powered platform, and write it once in your stack of choice, and release libraries for clients (mobile apps, integrations, web apps). Even so, a e2e test suite would surely serve far more utility over a spec that simply stubs out endpoints with no functionality.
Earlier quoted context omitted.
+1. It even looks very similar to TypeScript. Why not use TypeScript as a description of APIs in the first place? Get TypeScript types and even generate OpenAPI schema on the fly to serve it at `/openapi`?
Exactly - this is already a solved problem. https://docs.nestjs.com/openapi/introduction
Earlier quoted context omitted.
TypeScript type system is very advanced. It won't be possible to generate corresponding bindings for all popular languages, while keeping them idiomatic. I'd prefer API language to be very simple and straightforward.
OpenAPI's 'type system' is surprisingly advanced also, supporting explicitly discriminated unions and other things like that, which doesn't model well into all other languages.
I believe recent versions of OpenAPI are "compatible" with JSON Schema (at least they "wanted to be" last I checked as I was implementing some schema converters).
Even TypeScript is not enough to represent all of JSON Schema! But it gets close (perhaps if you remove validation rules and stuff like that it's a full match).
But even something like Java can represent most of it pretty well, specially since sealed interfaces were added. I know because I've done it :).
Earlier quoted context omitted.
What if you need to generate two server implementations (possibly in different languages) that adhere to the same specification? You don’t always go server -> spec -> client.
That seems like a rare use case. Surely we optimise for the general use case - you start working on a new server powered platform, and write it once in your stack of choice, and release libraries for clients (mobile apps, integrations, web apps). Even so, a e2e test suite would surely serve far more utility over a spec that simply stubs out endpoints with no functionality.
Earlier quoted context omitted.
Spec-first approach works better when client and server teams work on their parts simultaneously and need some contract before the implementation starts.
I can see the appeal there, but I can only imagine it's utility diminishes quickly over time as product evolves, and probably doesn't survive past implementation kickoff. Last thing developers love to do is to have to update a spec after having to update multiple tests and server code. If it does become a long lived artifact, CI/CD must also be a nightmare, having to figure out which commit matches which version of t…
For example, the problem of matching commits with specs doesn’t even exist in environments without continuous deployment (which is rarely a real necessity and often is even undesirable). You just tag your releases in VCS (can be easily automated) and track their scope in documentation (job of responsible product and engineering managers which know what goes live and when).
What is wrong with protobufs and grpc?