Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Access API docs with more context around interaction & remove outdated information #1151

Open
sisyphusSmiling opened this issue Oct 21, 2022 · 1 comment
Assignees
Labels
Document A document or group of documents for publication on the Docs Site or elsewhere (eg totorial, blog) Feedback

Comments

@sisyphusSmiling
Copy link
Contributor

sisyphusSmiling commented Oct 21, 2022

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:

  1. Tried onboarding to Alchemy only to remember they're no longer partnered with Flow - mention of Alchemy should be removed to avoid confusion
  2. Figure out how to interact with a gRPC API - settled on gRPCurl as my cli client
  3. Figure out how to get the API definition so I could interact with the API using my client - I ended up importing access.proto from flow/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).

Screen Shot 2022-10-21 at 11 38 20 AM

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

@sisyphusSmiling sisyphusSmiling added Feedback Document A document or group of documents for publication on the Docs Site or elsewhere (eg totorial, blog) labels Oct 21, 2022
@daorren
Copy link

daorren commented Jun 21, 2024

good advice!
why is it still ignored in 2024
simply adding reflection to grpc service, can make grpcurl users feel much better

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Document A document or group of documents for publication on the Docs Site or elsewhere (eg totorial, blog) Feedback
Projects
None yet
Development

No branches or pull requests

3 participants