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

Minor documentation issues in Control API #2318

Open
mattheworiordan opened this issue Nov 29, 2024 · 0 comments
Open

Minor documentation issues in Control API #2318

mattheworiordan opened this issue Nov 29, 2024 · 0 comments
Labels
bug A broken link, image etc

Comments

@mattheworiordan
Copy link
Member

mattheworiordan commented Nov 29, 2024

See https://ably.com/docs/account/control-api.

  1. Wording needs improving at the outset:

MO screenshot 2024-11-29 at 15 35 36

  1. Diagram may need reviewing?

MO screenshot 2024-11-29 at 15 38 57

  1. No mention of Terraform

Given Ably's Terraform dominates control API usage and is arguably the recommended approach for infrastructure integration, it deserves a big call out here, long before OpenAPI IMHO.

  1. Mention of Control API for stats is inconsistent

See screenshot below. Issues are:

  • Control API mention is inconsistent with remaining stats docs on how to access states (why is it mentioned at the top)
  • App and account stats docs are inconsistent
  • Documentation around fields is not up to date with latest schema

MO screenshot 2024-11-29 at 15 03 17

  1. Whilst you're at it, screenshots could be updated :) Nav is wrong, and capabilities have been extended (to include stats).

  2. Instructions on how to find your account ID and app ID don't use the control API to get this info?

See https://ably.com/docs/account/control-api#account-id and https://ably.com/docs/account/control-api#app-id. It makes no mention of the /me and /apps/list control API endpoints! We should dogfood our own API for this, and offer that as a secondary option.

@mattheworiordan mattheworiordan added the bug A broken link, image etc label Nov 29, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug A broken link, image etc
Development

No branches or pull requests

1 participant