This is very much possible, and I have done it, and it works great once it's all wired up.
But OpenAPI is verbose to the point of absurdity. You can't feasibly write it by hand. So you can't do schema first development. You need an open API compatible lib for authoring your API, you need some tooling to generate the schema from the code, then you need another tool to generate types from the schema. Each step tends to implement the spec to varying degrees, creating gaps in types, or just outright failing.
Fwiw I tried many, many tools to generate the typescript from the schema. Most resulted in horrendous, bloated code. The official generators especially. Many others just choked on a complex schema, or used basic string concatenation to output the typescript leading to invalid code. Additionally the cost of the generated code scales with the schema size, which can mean shipping huge chunks of code to the client as your API evolves
The tool I will wholeheartedly recommend (and which I am unaffiliated beside making a few PRs) is openapi-ts. It is fast and correct, and you pay a fixed cost - there's a fetch wrapper for runtime and everything else exists at the type level.
I was kinda surprised how bad a lot of the tooling was considering how mature OpenAPI is. Perhaps it's advanced in the last year or so, when I stopped working on the project where I had to do this.
I imagine you are very much in the minority. A simple hello world is like a screen full of yaml. The equivalent in graphql (or typespec which I always wanted to try as an authoring format for openapi https://typespec.io/) would be a few lines
I see your point, yet writing openapi specs by hand is pretty common.
There is the part where dealing with another tool isn't much worth it most of the time, and the other side where we're already reading/writing screens of yaml or yaml like docs all the time.
Taking time to properly think about and define an entry point is reasonable enough.
Agree with the other comments about writing OpenAPI by hand. It’s really not that bad at all, and most certainly not “verbose to the point of absurdity.”
Moreover, system boundaries are the best places to invest in being explicit. OpenAPI specs really don’t have that much overhead (especially if you make use of YAML anchors), and are (usually) suitably descriptive to describe the boundary.
In any case, starting with a declarative contract/IDL and doing something like codegen is a great way to go.
YAML OpenAPI schema, like SQL, is quite easy to write by hand and more importantly by AI. Telling AI to keep the openapi in sync with the latest changes made on an API works great and can even help you identify inconsistencies.
Ha yes, see one of my other comments to another reply.
I never got to use it when I last worked with OpenAPI but it seemed like the antidote to the verbosity. Glad to hear someone had positive experience with it. I'll definitely try it next time I get the chance
There is json-schema which is a sort of dialect/extension of OpenAPI which offers support for fetching relations (and relations of relations etc) and selecting a subset of fields in a single request https://json-schema.org/
I used this to get a fully type safe client and API, with minimal requests. But it was a lot of work to get right and is not as mainstream as OpenAPI itself. Gql is of course much simpler to get going
You still require gql requests to deal with. There's pretty much the same amount of code to build in BFF as it is to build the same in GQL... and probably less code on the frontend.
The value of GQL is pretty much equivalent to SOA orchestration - great in theory, just gets in the way in practice.
Oh and not to mention that GQL will inadvertently hide away bad API design(ex. lack of pagination).. until you are left questioning why your app with 10k records in total is slow AF.
Your response is incredibly anecdotal (as is mine absolutely), and misleading.
GQL paved the way for a lot of ergonomics with our microservices.
And there's nothing stopping you from just adding pagination arguments to a field and handling them. Kinda exactly how you would in any other situation, you define and implement the thing.
Thanks for mentioning this. I always find it unsettling when I've researched solutions for something and only find a better option from a random HN comment.
Fwiw I tried every tool imaginable a few years ago including kubb, (which I think I contributed to while testing things out)
The only mature, correct, fast option with a fixed cost (since it mostly exists at the type level meaning it doesn't scale your bundle with your API) was openapi-ts. I am not affiliated other than a previous happy user, though I did make some PRs while using it https://openapi-ts.dev/
And yes, current models are amazing at reducing time it takes to push out a feature or fix a bug. I wouldn't even consider working at a company that banned use of AI to help me write code.
PS: It's also irrelevant to whether it's AI generated or not, what matters is if it works and is secure.
There are literally users here that say that it works.
And you presume that the code hasn't been read or understood by a human. AI doesn't click merge on a PR, so it's highly likely that the code has been read by a human.
tRPC sort of does this (there's no spec, but you don't need a spec because the interface is managed by tRPC on both sides). But it loses the real main defining quality of gql: not needing subsequent requests.
If I need more information about a resource that an endpoint exposes, I need another request. If I'm looking at a podcast episode, I might want to know the podcast network that the show belongs to. So first I have to look up the podcast from the id on the episode. Then I have to look up the network by the id on the podcast. Now, two requests later, I can get the network details. GQL gives that to me in one query, and the fundamental properties of what makes GQL GQL are what enables that.
Yes, you can jam podcast data on the episode, and network data inside of that. But now I need a way to not request all that data so I'm not fetching it in all the places where I don't need it. So maybe you have an "expand" parameter: this is what Stripe does. And really, you've just invented a watered down, bespoke GraphQL.
I think BFF works at a small scale, but that's true with any framework. Building a one off handful of endpoints will always be less work than putting a framework in place and building against it.
GQL has a pretty substantial up front cost, undeniably. But you hopefully balance that with the benefit you'd get from it.
If you generate OpenAPI specs, and clients, and server type definitions from a declarative API definition made with Effect's own @effect/platform, it solves even more things in a nicer, more robust fashion.
