flow icon indicating copy to clipboard operation
flow copied to clipboard

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

Open sisyphusSmiling opened this issue 2 years ago • 1 comments

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 avatar Oct 21 '22 17:10 sisyphusSmiling