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.

Sign up for GitHub

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

Add automation for first two CAT APIs #8930

Merged
merged 6 commits into from
Dec 19, 2024
Merged

Add automation for first two CAT APIs #8930

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ac3055f
Add automation for first three CAT APIs
Naarcha-AWS Dec 11, 2024
c29685d
Merge branch 'main' into api-reference-cat
Naarcha-AWS Dec 19, 2024
be747a7
Add pointers for Aliases and Allocation. Remove for cluster_manager.
Naarcha-AWS Dec 19, 2024
a7205d1
Merge branch 'main' into api-reference-cat
Naarcha-AWS Dec 19, 2024
d33d12a
Add updated specs
Naarcha-AWS Dec 19, 2024
29f17f3
Update _api-reference/cat/cat-allocation.md
Naarcha-AWS Dec 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 20 additions & 8 deletions _api-reference/cat/cat-aliases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,20 +16,32 @@
The CAT aliases operation lists the mapping of aliases to indexes, plus routing and filtering information.


## Path and HTTP methods

<!-- spec_insert_start
api: cat.aliases
component: paths_and_http_methods
-->
## Paths and HTTP methods
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Paths and HTTP methods
## Path and HTTP methods

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want Paths when there many and Path when there's one?
Or do want a universal one? If it's universal then Paths and HTTP methods makes more sense.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I prefer Paths and HTTP methods. If we need to change to the singular (which in this case we don't, since multiple path types exist), we can exclude the header and modify it in the options.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nhtruong: @kolchfa-aws and I discussed it. Path would be more accurate than Paths since each x-operation-id usually encompasses one path in the API. We'll use omit_header if the writer chooses to include multiple paths on a single page.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Multiple paths on a single page would still be documented as different APIs and thus be in different sections.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use Path and HTTP methods per the API Style Guide.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's use "Endpoints" because "API operation" is not specific enough.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My primary concern here is consistency. If we want to use "Endpoints", that's fine, but let's reflect that in the template as well as in the relevant docs. Thanks.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll change the template and the wording in a separate PR.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR is up #8959

```json
GET _cat/aliases/<alias>
GET _cat/aliases
GET /_cat/aliases
GET /_cat/aliases/{name}
```
{% include copy-curl.html %}
<!-- spec_insert_end -->

<!-- spec_insert_start
api: cat.aliases
component: query_parameters
-->
## Query parameters

Parameter | Type | Description
:--- | :--- | :---
local | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`.
expand_wildcards | Enum | Expands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
`expand_wildcards` | String / String / String / String / List | Whether to expand wildcard expression to concrete indexes that are open, closed or both.

Check failure on line 37 in _api-reference/cat/cat-aliases.md

View workflow job for this annotation

GitHub Actions / vale

[vale] _api-reference/cat/cat-aliases.md#L37 

[OpenSearch.SpacingSlash] When using '/' between words, do not insert space on either side of it.
Raw output 
{"message": "[OpenSearch.SpacingSlash] When using '/' between words, do not insert space on either side of it.", "location": {"path": "_api-reference/cat/cat-aliases.md", "range": {"start": {"line": 37, "column": 22}}}, "severity": "ERROR"}

Check failure on line 37 in _api-reference/cat/cat-aliases.md

View workflow job for this annotation

GitHub Actions / vale

[vale] _api-reference/cat/cat-aliases.md#L37 

[OpenSearch.SpacingSlash] When using '/' between words, do not insert space on either side of it.
Raw output 
{"message": "[OpenSearch.SpacingSlash] When using '/' between words, do not insert space on either side of it.", "location": {"path": "_api-reference/cat/cat-aliases.md", "range": {"start": {"line": 37, "column": 40}}}, "severity": "ERROR"}
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are there 4 instances of String in the type? Also, as a rule, we don't want slashes to signify "or". I would suggest "String or list". Also, the old description had supported values, which is helpful, and specified that the list should be comma-separated. The new description has less information.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nhtruong: IS there something in the spec that would cause this?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's coming form the spec. I'll update the code to handle this edge case.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. Let me know once that update is through and I'll update this PR with the updated descriptions.

`format` | String | A short version of the Accept header (for example, `json`, `yaml`).
`h` | List | Comma-separated list of column names to display.
`help` | Boolean | Return help information.
`local` | Boolean | Return local information, do not retrieve the state from cluster-manager node.
`s` | List | Comma-separated list of column names or column aliases to sort by.
`v` | Boolean | Verbose mode. Display column headers.
<!-- spec_insert_end -->

## Example requests

Expand Down
32 changes: 24 additions & 8 deletions _api-reference/cat/cat-allocation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,20 +15,36 @@ has_children: false
The CAT allocation operation lists the allocation of disk space for indexes and the number of shards on each node.


## Path and HTTP methods

<!-- spec_insert_start
api: cat.allocation
component: paths_and_http_methods
-->
## Paths and HTTP methods
```json
GET _cat/allocation?v
GET _cat/allocation/<node_name>
GET /_cat/allocation
GET /_cat/allocation/{node_id}
```
<!-- spec_insert_end -->


## Query parameters

<!-- spec_insert_start
api: cat.allocation
component: query_parameters
-->
## Query parameters
Parameter | Type | Description
:--- | :--- | :---
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We also need to specify defaults for the query parameters that have them (e.g., local).

bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
local | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`.
cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
`bytes` | String | The unit used to display byte values.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`bytes` | String | The unit used to display byte values.
`bytes` | String | The units used to display byte values.

`cluster_manager_timeout` | String | Operation timeout for connection to cluster-manager node.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`cluster_manager_timeout` | String | Operation timeout for connection to cluster-manager node.
`cluster_manager_timeout` | String | A timeout for connection to the cluster manager node.

`format` | String | A short version of the Accept header (for example, `json`, `yaml`).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`format` | String | A short version of the Accept header (for example, `json`, `yaml`).
`format` | String | A short version of the HTTP accept header (for example, `json` or `yaml`).

`h` | List | Comma-separated list of column names to display.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`h` | List | Comma-separated list of column names to display.
`h` | List | A comma-separated list of column names to display.

`help` | Boolean | Return help information.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`help` | Boolean | Return help information.
`help` | Boolean | Whether to return help information.

`local` | Boolean | Return local information, do not retrieve the state from cluster-manager node.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`local` | Boolean | Return local information, do not retrieve the state from cluster-manager node.
`local` | Boolean | If `true`, specifies to retrieve information only from the local node. If `false`, specifies to retrieve local information from the cluster manager node.

`s` | List | Comma-separated list of column names or column aliases to sort by.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`s` | List | Comma-separated list of column names or column aliases to sort by.
`s` | List | A comma-separated list of column names or column aliases to sort the response.

`v` | Boolean | Verbose mode. Display column headers.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`v` | Boolean | Verbose mode. Display column headers.
`v` | Boolean | Whether to display column headers.

`master_timeout` <br> _DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ Operation timeout for connection to cluster-manager node.
<!-- spec_insert_end -->

## Example requests

Expand Down
27 changes: 24 additions & 3 deletions _api-reference/cat/cat-cluster_manager.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,32 @@ has_children: false
The CAT cluster manager operation lists information that helps identify the elected cluster manager node.


## Path and HTTP methods

<!-- spec_insert_start
api: cat.cluster_manager
component: paths_and_http_methods
-->
## Paths and HTTP methods
```json
GET _cat/cluster_manager
GET /_cat/cluster_manager
```
<!-- spec_insert_end -->

<!-- spec_insert_start
api: cat.cluster_manager
component: query_parameters
-->
## Query parameters
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comments as above.

Parameter | Type | Description
:--- | :--- | :---
`cluster_manager_timeout` | String | Operation timeout for connection to cluster-manager node.
`format` | String | A short version of the Accept header (for example, `json`, `yaml`).
`h` | List | Comma-separated list of column names to display.
`help` | Boolean | Return help information.
`local` | Boolean | Return local information, do not retrieve the state from cluster-manager node.
`s` | List | Comma-separated list of column names or column aliases to sort by.
`v` | Boolean | Verbose mode. Display column headers.
`master_timeout` <br> _DEPRECATED_ | String | _(Deprecated since 2.0: To promote inclusive language, use `cluster_manager_timeout` instead.)_ Operation timeout for connection to cluster-manager node.
<!-- spec_insert_end -->

## Query parameters

Expand Down
Loading