onflow / onflow/flow

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

Open
#1,151 1 comment 2 reactions 1 assignee View on GitHub

@10thfloor is already working on this.

Since Oct 21, 2022.

Document Feedback
Dominant language
Go
Stars
361
Forks
159
PR merge metrics
No merged PRs in 30d

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.