Our great sponsors
-
-
connexion
Connexion is a modern Python web framework that makes spec-first and api-first development easy.
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
-
-
-
-
msgpack-javascript
@msgpack/msgpack - MessagePack for JavaScript / msgpack.org[JavaScript/TypeScript/ECMA-262]
-
InfluxDB
Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.
Good idea to add to the comparisons page!
The `openapi-typescript` is a library for generating types from openapi spec, similar to the `openapicmd typegen` command provided by openapi-stack.
The new openapi-typescript-fetch seems similar to openapi-client-axiow, but using fetch instead of axios for a more lightweight approach.
Both libraries are great and well aligned with goals of openapi-stack!
In addition to type generation and consuming APIs, https://openapistack.co provides tools for building and mocking API backends with the openapi-backend library, as well as a general cli tool to work with openapi files and invoke APIs via the command line.
The core mission of https://openapistack.co is to provide an end to end full stack toolkit for building and consuming typesafe REST APIs.
> While REST APIs don't generally provide the same level of control to clients as GraphQL, many times this could be seen as a benefit especially in scenarios where strict control over data access and operations is crucial.
Rest is more secure, cacheable, and more performant on the server side as field resolution doesn't need to happen like it does with GraphQL. It is not more performant on the client side, and this is a trade-off, but I favor rest applications over GraphQL ones as a DevOps engineer. They are much easier to administer infrastructure-wise, I can cache the requests, etc.
Data at our company suggests that several small queries actually do better performance-wise than one large one. We switched to GraphQL a year and a half ago or so, but this piece of data seems to suggest that we might have been better off just sticking with REST. My suggestion to that effect was not met with optimism either on the client or server side. Apparently there are server-side benefits as well, allowing for more modular development or something like that.
I have used OpenAPI using connexion[1]. It was hard to understand at first, but I really liked that the single source of truth was one schema. It also made it really easy to develop against the API because it came with a UI that showed the documentation for all the rest end points and even had test buttons.
1: https://connexion.readthedocs.io/en/latest/
Thank you for your encouraging words and insights!
There are indeed popular DSLs and code to openapi solutions out there. Many of which are easy to plug in to the openapi-stack libraries btw!
I guess I personally always found it frustrating to try to control the generated OpenAPI output using additional tooling and ended up preferring yaml + a visualisation tool as the api design workflow. (e.g. swagger editor)
But something like https://buildwithfern.com, or using zod as substitute for json schema may indeed be worth a try as a step before emitting openapi.
Cheers! Going from code first to schema first is definitely worth it in my experience! Especially when working in a team.
The nice thing is you already have an openapi spec, so it’s pretty trivial to eject from fastify swagger and switch to openapi-backend if you want!
Here’s an example of openapi-backend running on Fastify
https://github.com/openapistack/openapi-backend/tree/main/ex...
Strong disagree.
The barrier you presume is that OpenAPI specs are hard to write. Raw oAPI in yaml is indeed a pain, but there are good DSL's out there.
I personally love Zod->OpenAPI, via https://ts-rest.com which uses https://www.npmjs.com/package/@anatine/zod-openapi. https://github.com/asteasolutions/zod-to-openapi is another alternative for Zod.
> The big bonus of the human documentation approaches today is that time is somewhat combined with building the client.
This is wild to me; human documentation is absurdly error-prone and it's almost always and immediately out of date. (Zod or other DSL) -> OpenAPI -> generated docs (and types! and clients! and mocks!) are always going to be better; always accurate, and faster. The upfront cost is slightly higher, but the ROI is _significant_.
OpenAPI specs lend themselves to excellent docs, ala Mintify or Docusaurus. Even interactive ones, like Swagger UI. The vast majority of API browsers & tooling understands OAPI, so why re-create (an often incomplete) version of the truth when using those tools?
> Whatever is overall fastest and gets me on to the problems I'm really trying to solve.
You may start (slightly) faster, but you'll incur significant cost when you move past the "trivial implementation" stage.
For instance:
GraphQL's first draft release was 8 years ago. [1]
It's first non-draft release was 5 years ago. [2]
It's first release under a community foundation was 2 years ago. [3]
[1] https://spec.graphql.org/July2015/
[2] https://github.com/graphql/graphql-spec/releases/tag/June201...
[3] https://github.com/graphql/graphql-spec/releases/tag/October...
For a compact message format being sent to browsers, you might look at messagepack, eg with https://github.com/msgpack/msgpack-javascript – it's essentially binary JSON, so it'd be compatible with OpenAPI specs.
I think the ser/des is slower than JSON in most browsers, but the message format is smaller.
Oftentimes, using a query parameter like `?exclude[]=…` or `?include[]=…` or similar to say "only get me these response fields, not the whole object" can be useful for this too (and then you still get JSON back).