WIP: Cross-Reference API Endpoints & CLI Commands; Include Command ACL Info

[jkirschner-hashicorp]

Intended to close #3134. Meant to accomplish:

• Just like we give additional info (e.g., required ACLs) for using HTTP API endpoints, we should provide the same info for CLI commands
• CLI commands and HTTP API endpoints should cross-reference each other in the docs, in case the user (1) is looking for one but ends up on the other, such as through a Google search, or (2) wants to convert from one usage to another.

We should align on a consistent approach for one command/endpoint before applying the approach to all commands/endpoints.

Steps:

• Align on consistent approach for one endpoint
• Align on how to make this information easy to manage (e.g., include some of the info in partials?)
• Deploy approach across all commands/endpoints (based on a spreadsheet I've created mapping CLI commands, HTTP API endpoints, and required ACLs)

[hashicorp-ci]

🤔 This PR has changes in the website/ directory but does not have a type/docs-cherrypick label. If the changes are for the next version, this can be ignored. If they are updates to current docs, attach the label to auto cherrypick to the stable-website branch after merging.

[jkirschner-hashicorp]

@karl-cardenas-coding, @trujillo-adam, @blake : we should align on a consistent approach for one command/endpoint before I proceed any further. I've created some possible approaches for you to react to (that exist in this PR's diff and have been rendered into the images below).

In all images, the light blue box shows the content that has been added / differs between options. Let me know what your thoughts on which options are best or other options to try.

Cross-referencing HTTP API endpoints from command docs

TLDR: pick option 1?

I think option 1 is much more scannable, though it won't be visually consistent with its counterpoint cross-ref on the HTTP API endpoint docs page (see options below). Still, I think option 1 is better.

Cross-referencing CLI Commands from HTTP API endpoints docs

TLDR: pick option 1? But if we pick option 2 instead, we might want to pick option 2 above as well.

Option 1 is more scannable. Unfortunately, by adding a column, there's less space for some other columns (like the endpoint). For some endpoints, the content may wrap onto two lines... though I'm not sure that's a big deal. Maybe there's a more concise, but still clear, column header than "Corresponding CLI Command".

Option 2 can be made consistent with its counterpoint cross-ref on the command docs page (see option 2 above).

Including ACL Info in CLI command docs

TLDR: maybe the table from option 3, but decide whether/how we mention blocking queries, agent caching, and other consistency modes (consistent) not supported by commands but may be by the corresponding HTTP API endpoint?

Options 1 and 2: I wanted to follow the same structure as on the HTTP API endpoint docs, but if we only have one column (because some of the other columns don't apply) ... it looks weird. I suppose we could just have a text line that says "ACL Required: none" instead of a table ... (EDIT: which is now option 5).

Option 3: technically, some commands support the stale consistency mode through the -stale flag. So this gives us a second column. Maybe this is the best option, since it's scannable and the most complete for what the command itself supports? (Options 1,2,5 don't provide a means to show consistency modes where supported.)

Option 4: gives the most complete information, but I find it very confusing to mix what's directly supported by the command versus what would be supported if the corresponding HTTP API endpoint was used instead. Included to have some variety to consider, but I don't think this is a good option.

Options 2-4 try different approaches to mention blocking queries, agent caching, and other consistency modes (consistent) that may be available via the HTTP API endpoint, but aren't via command. Option 1 chooses not to mention any of this. Which approach do you think makes the most sense for mentioning (or not) this specific info?

Option 5: simple, but not visually consistent with how the HTTP API endpoint docs present this info. Also doesn't include consistency mode.

[karl-cardenas-coding]

@jkirschner-hashicorp

I really like the options you have put together and thank you for making it easier for us all to review. Here are my thoughts.

Cross-referencing HTTP API endpoints from command docs -> Option 1

Cross-referencing CLI Commands from HTTP API endpoints docs -> Option 1

Including ACL Info in CLI command docs -> Option 3

I agree with all the points you made. The ACL info was a bit tougher to choose, but I think adding too much detail increases the complicity and could result in practitioners getting intimidated. Option 3 seems to be a good sweet spot imo.

[jkirschner-hashicorp]

@trujillo-adam, @blake : any different opinions? It seems like @karl-cardenas-coding and I are both thinking:

Cross-referencing HTTP API endpoints from command docs -> Option 1

Cross-referencing CLI Commands from HTTP API endpoints docs -> Option 1

Including ACL Info in CLI command docs -> Option 3

[trujillo-adam]

Regarding the Cross-referencing HTTP API endpoints from command docs change, I like the endpoint cross-ref in a paragraph under the description because my assumption is that the users' primary goal is get information about the command; the API endpoint is secondary.

Regarding the Cross-referencing CLI Commands from HTTP API endpoints docs change, I generally like adding the command to the table, but I wonder if we should take this opportunity to reconsider which columns we're standardizing on. would want to know what kind fo payloads a PUT or POST takes and what parameters are available, and which params are required. Does a table even make sense considering that there is only one row of data? I'me sure we've done it in the past, but it was probably driven by the context, i.e., done to maintain consistency within the same page of content. It's great that you are adding this info to the API refs, but it should be implemented as part of a larger improvement strategy. We should have that discussion outside of this PR.

Regarding the Including ACL Info in CLI command docs change, while I think we should be using tables more often, I am not sure that a single-row of information in table format is better than a bulleted list. That said, I am onboard with providing complete information a la option #4.

[jkirschner-hashicorp]

@trujillo-adam: thanks for the input! A few follow-ups.

Regarding the Cross-referencing CLI Commands from HTTP API endpoints docs change, I generally like adding the command to the table, but I wonder if we should take this opportunity to reconsider which columns we're standardizing on. would want to know what kind fo payloads a PUT or POST takes and what parameters are available, and which params are required. Does a table even make sense considering that there is only one row of data? I'me sure we've done it in the past, but it was probably driven by the context, i.e., done to maintain consistency within the same page of content. It's great that you are adding this info to the API refs, but it should be implemented as part of a larger improvement strategy. We should have that discussion outside of this PR.

I'd advocate for a good solution sooner rather than making no changes until we have a future, more perfect solution.

I'm totally onboard with a larger improvement strategy to how we present that kind of information for APIs (existing docs) and commands (proposed in this PR). But if that may not happen soon, there's only upside in providing the information now:

• Users who want this information benefit in the interim
• This information will be available in the MDX files already whenever the larger improvement happens, making that implementation easier

Q: What are your thoughts? And if you agree, do you think option 1 or 2 makes more sense as an interim solution?

Regarding the Including ACL Info in CLI command docs change, while I think we should be using tables more often, I am not sure that a single-row of information in table format is better than a bulleted list. That said, I am onboard with providing complete information a la option 4

Q: What are your thoughts on option 3 (which only has two items)? It's the most "complete" in terms of what's available via the command.

Regarding the Cross-referencing HTTP API endpoints from command docs change, I like the endpoint cross-ref in a paragraph under the description because my assumption is that the users' primary goal is get information about the command; the API endpoint is secondary.

Summary: lots of words to say "I'm on the fence about options 1 + 2".

Based purely on my own experience (not based on any user observation/studies), I'm not sure it's always the case that the user's primary goal is to get information about the command. For example, when I've wanted to figure out how to create an intention in Consul, my workflow is typically to Google search "Consul create intention" and click on whatever link shows up that seems relevant. Sometimes I end up on the "Command" page when I really wanted the HTTP API, and vice-versa.

Regardless of the percentage breakdown, we probably have a mix of people who:

• Case A: Are intentionally on the command page
• Case B: Ended up on the command page because it's where their search took them, even if it's not exactly what they want

I agree with you that option 2 is better for Case A. I think option 1 is better for Case B. But I think either option can be acceptable for both cases. If Case A is more common, option 2 is probably better...

That said, it feels a bit strange (inconsistent) to choose option 2 for "CMD: CROSS-REFERENCING" but not option 2 for "API: CROSS-REFERENCING".

[trujillo-adam]

Sorry for the long pause on this.

I'm totally onboard with a larger improvement strategy to how we present that kind of information for APIs (existing docs) and commands (proposed in this PR).

I'm kind of surprised we don't use swagger or some other API docs generator. Perhaps we can bring this up with the team putting together the new docs website.

Q: What are your thoughts? And if you agree, do you think option 1 or 2 makes more sense as an interim solution?

I'm still struggling with the concept of bolting on a solution (albeit, an improvement) to the existing framework. Tables are awesome for organizing related info, but single-row and two-column tables might create too much maintenance overhead (especially in MD) because the code can get so ugly. That said, what if we go with something like this:

Description	This endpoint returns all checks that are registered with the local agent. These checks were either provided through configuration files or added dynamically using the HTTP API. Checks known to the agent may be different from those reported by the catalog. This is usually due to changes being made while there is no leader elected. The agent performs active anti-entropy, so in most situations everything will be in sync within a few seconds.
Method	GET
Path	/agent/checks
Produces	application/json
Blocking queries	none
Consistency modes	none
Agent caching	non
Required ACLs	node:read service:read
Corresponding CLI	none

Rather than creating multiple single-row tables, we just do a two-column table with all components listed. Better yet, we can skip the table and just create a list.

Description

This endpoint returns all checks that are registered with the local agent.
These checks were either provided through configuration files or added dynamically using the HTTP API.
Checks known to the agent may be different from those reported by the catalog.
This is usually due to changes being made while there is no leader elected.
The agent performs active anti-entropy, so in most situations everything will be in sync within a few seconds.

Details

• Method: GET
• Path: /agent/checks
• Produces: application/json
• Blocking queries: none
• Consistency modes: none
• Agent caching: none
• Required ACLs: node:read, service:read
• Corresponding CLI: none

Regarding the Including ACL Info in CLI command docs change, while I think we should be using tables more often, I am not sure that a single-row of information in table format is better than a bulleted list. That said, I am onboard with providing complete information a la option 4

Q: What are your thoughts on option 3 (which only has two items)? It's the most "complete" in terms of what's available via the command.

It looks like we have some precedent for describing this info:
https://www.consul.io/commands/exec

I'm all for providing the most complete information, but if there isn't a compelling reason to describe the information in a table (two-column, single-row) we should just use a list. If the list items can't be stated concisely, then it usually indicates that a subsection should be created to keep the content scannable.

Regarding the Cross-referencing HTTP API endpoints from command docs change, I like the endpoint cross-ref in a paragraph under the description because my assumption is that the users' primary goal is get information about the command; the API endpoint is secondary.

Summary: lots of words to say "I'm on the fence about options 1 + 2".

Based purely on my own experience (not based on any user observation/studies), I'm not sure it's always the case that the user's primary goal is to get information about the command. For example, when I've wanted to figure out how to create an intention in Consul, my workflow is typically to Google search "Consul create intention" and click on whatever link shows up that seems relevant. Sometimes I end up on the "Command" page when I really wanted the HTTP API, and vice-versa.

Regardless of the percentage breakdown, we probably have a mix of people who:

• Case A: Are intentionally on the command page

We know that people discover content the way you describe, but we should be logically consistent for the given context and assume that people accessed this page because they want to learn about the command. I prefer option 2.

• Case B: Ended up on the command page because it's where their search took them, even if it's not exactly what they want

I agree with you that option 2 is better for Case A. I think option 1 is better for Case B. But I think either option can be acceptable for both cases. If Case A is more common, option 2 is probably better...

That said, it feels a bit strange (inconsistent) to choose option 2 for "CMD: CROSS-REFERENCING" but not option 2 for "API: CROSS-REFERENCING".

I don't think this matters--they are completely different sections.

[jkirschner-hashicorp]

Closing this unmerged. The work started here was carried forward in two other PRs since merged:

• Docs: Update CLI commands to show corresponding HTTP API commands and ACL policies required #11984
• Docs: Updating HTTP API endpoints with CLI equivalent links #12004