flow
flow copied to clipboard
Update Access API docs with more context around interaction & remove outdated information
Introduction
After teaching myself to interact with the Access API, I found the docs a bit lacking with regards to onboarding. My discovery process was basically the following:
- Tried onboarding to Alchemy only to remember they're no longer partnered with Flow - mention of Alchemy should be removed to avoid confusion
- Figure out how to interact with a gRPC API - settled on gRPCurl as my cli client
- Figure out how to get the API definition so I could interact with the API using my client - I ended up importing
access.proto
fromflow/protobuf/flow/access/access.proto
This then allowed me to interact with the API, but clearer docs would've saved me time and confusion. After seeing we have an OpenAccess REST API, I download Swagger Viewer VS Code extension. Once I did, I was able to preview and interact with the API in a simple UI, making requests significantly easier (see screenshot below).

Suggestion
Based on my onboarding experience, I'd recommend a couple things:
- Update the docs to remove outdated material
- Include mention of REST API
- Add context for:
- Interacting with a gRPC API, maybe linking to a learning resource on how to do so and a suggested open-source client like gRPCurl
- Examples of a few commands using the suggested client(s)
- Interacting with REST API, either via cli and/or documenting how one would leverage Swagger for ease of use
One last request that, if possible, would probably be its own issue - adding reflection to the gRPS API. This would allow them to simply list the API methods so that devs don't have to load the .proto
themselves.
P.S. Bonus issue - the link in protobuf/README.md
is broken