Propose strategy for promoting documentation of our APIs

[lightwalker-eth]

This issue is focused on proposing answers to these questions, not actually executing that proposal yet.

Open questions / goals:

• Should we define (and maintain) a Swagger?
• We need to explicitly document alerts that our APIs are all currently in "Alpha" status and that they should be expected to break on each version update as we are currently iterating very fast on them and don't want to offer backwards compatibility yet.
• How will we document and promote our APIs from the ENSNode docs website?
• How will we document and promote our APIs from ENSAdmin? Note how we currently are only giving visibility to the Subgraph GraphQL APIs there.
• What should we do with https://ensnode.io/examples ? Our strategy has been evolving and it's now clear that we should not be promoting use of the Subgraph-compatible GraphQL APIs as we will be working to sunset and ultimately remove those.

[notrab]

@lightwalker-eth

1. I think we should maintain an OpenAPI spec for our API. It's quite easy to automatically generate these using something like @hono/zod-openapi with our Hono API. These generated APIs can later be updated to automatically codegen our SDK (which we discussed doing a few months back).
2. tbd
3. We currently have a "Reference" section in our docs, but I think this is incorrectly named. We could introduce a "API Reference" section that lists the endpoints/input/output/params. I'm not sure if Astro has anything "out of the box" for this with their plugin ecosystem, but we could probably build something that did that. Mintlify does this kind of thing and it works quite well, so it would be a nice win for us to codegen these pages too. I do this with the Turso documentation quite quickly when the OpenAPI spec updates.
4. tbd
5. I see /examples as promotional material - implementation examples/examples that inspire to build, and while they should be kept up to date with our APIs. These should not be the source of truth to learn such APIs. Our API Reference should be that, and feed these examples.

[lightwalker-eth]

@notrab Cool thank you 👍

For next steps on this goal, can you propose a solution for how we both create and maintain an OpenAPI spec for our API and also how we give this OpenAPI spec visibility via our docs?

I am skeptical / cautious of any use of codegen here. My vision and expectation of our OpenAPI spec is to maximize for precision in our data models and how we communicate ideas. Open to suggestions but the goal is to make this API as absolutely amazing as possible, not to minimize our work. Minimizing our work is valuable only insofar as it helps us save more time to invest back in making the API as absolutely amazing as possible.

Please also note how each of the following services have their own APIs:

• ENSIndexer (most important API to focus on for now)
• ENSRainbow

[stevedylandev]

Found this through Epic #1361, I have some thoughts on this as well.

Should we define (and maintain) a Swagger?

If by Swagger you mean an OpenAPI spec, I would say absolutely yes. OpenAPI is an industry standard that can add meaningful DX for users. As @notrab mentioned the @hono/zod-openapi is likely the best route to take for implementation. We will have to implement and test for accuracy, but generally speaking the codegen is going to be far more accurate than the alternative which is rolling it by hand. I say that as someone who has had to do it both ways. The key to having an accurate spec via codegen is having accurate and strict typing. If the OpenAPI spec is generated and something doesn't match up, it very well could be the typing itself and help reveal weaknesses in our own codebase. There are exceptions of course but I feel pretty strongly about using an OpenAPI generator that works off our type system (Zod).

We need to explicitly document alerts that our APIs are all currently in "Alpha" status and that they should be expected to break on each version update as we are currently iterating very fast on them and don't want to offer backwards compatibility yet.

I think we can do this two ways. The first is to use a versioned path such as api/v1alpha/endpoint which clearly has the word alpha in it. Once we are comfortable with our v1 spec we can simply remove the alpha. Second, we can make it very clear in both internal codebase and hosted documentation that the API is under active development and cannot guarantee backwards compatibility. This also gives us a plug for people interested in the API to join our Telegram group so we can get better feedback from users testing it out.

How will we document and promote our APIs from the ENSNode docs website?

As @notrab also mentioned, there are not a lot of good OpenAPI options in Astro. The most notable is startlight-openapi which would take some overrides to make the styles match our current branding. Even then it would be a static rendering, which is not as high quality as an interactive spec (eg: https://docs.pinata.cloud/api-reference). This opens to a whole other discussion of whether or not we want to use a different docs framework entirely. I think our docs are still small enough that now is a good time to consider this and the pros and cons of such a move. For now, an OpenAPI spec is still the first step and a crucial one.

How will we document and promote our APIs from ENSAdmin? Note how we currently are only giving visibility to the Subgraph GraphQL APIs there.

I'm personally not sure if it would make sense to document from within ENSAdmin like we do now, outside of linking to the docs. However it is possible to still have a reference inside ENSAdmin like we do for the GraphQL APIs. I think this topic digs more into the question of what the core purpose of ENSAdmin is, which I don't have enough context to answer. Nevertheless, OpenAPI still enables these kinds of experiences for Rest APIs.

What should we do with https://ensnode.io/examples ? Our strategy has been evolving and it's now clear that we should not be promoting use of the Subgraph-compatible GraphQL APIs as we will be working to sunset and ultimately remove those.

Perhaps a conversation for a different thread related to DX and documentation, but I would personally vouch for moving that page to live inside the docs it would list example applications. Most library monorepos have an examples directory with different frameworks such as React or Node.js. Since the examples would live in the monorepo and share the packages within, it makes it easy to test and dogfood our SDKs and clients in real apps, and it gives users a chance to see how ENS Node is used in those contexts. /exmaples would simply be a list of the examples we built in the monorepo and link to them on GitHub.

In addition to examples I think we should also have quickstart guides for multiple frameworks, eg: https://docs.pinata.cloud/frameworks/next-js

[stevedylandev]

Once #1338 is merged we will want to discuss the above in regards to next steps for hosted documentation.