influxdata / influxdata/influxdb

Clarify information about tokens in API docs

Open
#19,656 0 comments 0 reactions 0 assignees View on GitHub
area/api-docs team/compute
Dominant language
Rust
Stars
31.7k
Forks
3.7k
Avg merge
13h 37m
Merged PRs (30d)
8

Description

@AlirieGray @brettbuddin @GeorgeMac
cc @stephanie-engel @rhajek

Currently, if folks search for "create a token"
https://docs.influxdata.com/influxdb/v2.0/api/

Screen Shot 2020-09-28 at 12 00 50 PM

We see "Create an authorization" 6th in the list. Not all folks are tying together "create a token" and "create an authorization"

- Perhaps we could add a key for the Create an authorization page, so results show both "Create an authorization" and "Create a token-based authorization" or "Create an authorization (token)".

- Under the "Create an authorization" heading, lets add statement directly under heading to clarify: _Create an authorization for a specified organization; this authorization defines permissions and creates a token to use in API requests._

- Next to description: A description of the authorization. Currently, all authorizations (create a token/are token-based?). ....Would folks ever use an existing token to create an authorization?

- Next to permissions: List of permissions for an authorization. Must have at least one permission. Add possible permissions-read/write/all access? Also, what is the "id" under permissions in the Response sample indicate?

- In the request and response samples, under permissions, does the id indicate the user ID and does name indicate the user name?

Contributor guide

Open the contributing guide

Research direction

Start with the InfluxDB API documentation page linked in the issue and inspect the “Create an authorization” heading, search result text, and request/response permission samples. Confirm the intended token terminology and the meanings of permission id and name, then update the heading, description, and examples so users searching for token creation can find and understand the endpoint.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.