Show HN: Fern, a language for defining REST APIs that compiles into OpenAPI

[zachkirsch]

https://github.com/fern-api/fern

Hi HN, this is Danny, Deep, and Zach.

We built Fern after our previous ed tech startup failed. We were frustrated with how much time we spent writing “API code” instead of working on the actual product. We tried to use OpenAPI but we were underwhelmed - the generated code wasn’t idiomatic and it still required manual work (custom templates, scripts, manually publishing SDKs to registries).

The Fern compiler takes your API as input and invokes generators that output things like: SDKs, server code, a Postman collection, and an OpenAPI spec.

Some technical highlights about the compiler + generators:

- The compiler (available as a CLI) handles syntactic + semantic validation. It also includes a linter that encodes best practices. If your API Definition compiles, you can have high confidence that the SDKs will generate correctly.

- After all the parsing and validation, the compiler outputs an intermediate representation that gets handed off to the generators. This prevents each generator from re-implementing the same parsing and validation logic.

- Each generator is implemented in the language it is targeting - e.g. the Python generators are written in Python, the TypeScript generators are written in TS. It makes the SDKs more idiomatic because every programming language generally has the best tooling/libraries for generating code in itself. We also think it’ll make community involvement + contribution easier.

- The generators can output the code to disk, but also push the code to a Github repo and publish the SDK directly to registries (e.g. npm, Maven).

We are looking for devs to use Fern for API development. If you have any feedback about the process, compiler, or the generated code, we’d love to hear it.

"Plant Store" example: https://github.com/fern-api/plantstore-api

Generated repos:

- https://github.com/fern-api/plantstore-node

- https://github.com/fern-api/plantstore-java

- https://github.com/fern-api/plantstore-postman

- https://github.com/fern-api/plantstore-openapi

[Existenceblinks]

(disclosure: I'm about to build my own version of this kind of thing)

Reading the https://www.buildwithfern.com/docs/why-fern page, I wonder why not Smithy? They also have 1:1 IDL:AST. Is it too complex for just HTTP-JSON api?

I'm quite inclined to just follow Smithy spec (or subset), they seem to encounter many edge cases e.g. client codegen backward compatibility (https://smithy.io/2.0/spec/type-refinement-traits.html#clien...)

If it is to avoid java based tooling, it is bad to build your-fav-lang tools around its AST? Skipping the IDL + java parser coupling part.

I'm thinking if it's inevitable in this space to always have N+1 standard-ish problem. I found that what I come up with it's pretty close to Smithy.

What do you think why not Smithy?

[zachkirsch → Existenceblinks]

Thanks for checking out Fern!

Smithy is an awesome library, and we love the VSCode extension that makes it easy to click around in the Smithy files.

We built our own spec because there's a lot of cool SDK features that aren't supported in Smithy. For example:

- Audiences. It should be easy in the spec to specify some endpoints as "internal only" to include them in the internal SDKs, but exclude them from the external SDKs.

- Per-endpoint errors. Smithy doesn't have a concept of specifying which non-200 responses a particular endpoint might return. It's super helpful in the SDKs to know which errors might be thrown from a particular endpoint.

- Pagination. It should be easy in the spec to specify that an endpoint is paginated, so the SDK is able to page through results easily (e.g. for-await in TypeScript). Note: this is a WIP and not yet released in Fern.

Having our own spec also lets us be more creative with the feature set we provide. For example, we want to add support for websockets and webhooks.

All that said, we're not aiming to be a competing standard. There's so much tooling already for these different specs, and it should be easy to convert between them. Our Smithy->Fern converter is in development so that Smithy users can take advantage of our SDK generators.

[Existenceblinks → zachkirsch]

Thanks for pointing out the why not.

> Our Smithy->Fern converter is in development so that Smithy users can take advantage of our SDK generators.

This is a good thing although there's definitely not going to be lossless.

Smithy trait seem to be an escape hatch for everything, I believe it could be used to achieve the same but maybe not easier. They already have pagination traits. And their http error is per operation, endpoint is also per operation, so I think the error is bound to operation as well (https://smithy.io/2.0/spec/http-bindings.html#httperror-trai...)

[zachkirsch → Existenceblinks]

> Smithy trait seem to be an escape hatch for everything, I believe it could be used to achieve the same but maybe not easier.

No doubt! This is definitely part of our thinking - there's a lot of things that are _possible_ in Smithy (and OpenAPI), but it requires you to be an expert and really understand how things work. For 90% of the use cases, it should be dead simple. For the remaining 10%, it's okay to rely on more complex features like plugins and traits.

[dflock]

Are you intending to monetize this, somehow?

[zachkirsch → dflock]

Yes, we are! We're planning on offering a paid site where all the generation and publishing happens in the cloud.

[r_thambapillai]

Love this guys well done