Add docs for QueryApiKey API by ywangd · Pull Request #76521 · elastic/elasticsearch

ywangd · 2021-08-14T09:14:01Z

This PR adds documentation for the new QueryApiKey API added in #75335 and #76144

doc-preview: https://elasticsearch_76521.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/security-api-query-api-key.html

Relates: #71023

elasticmachine · 2021-08-17T01:29:04Z

Pinging @elastic/clients-team (Team:Clients)

elasticmachine · 2021-08-17T01:29:05Z

Pinging @elastic/es-docs (Team:Docs)

elasticmachine · 2021-08-17T01:29:05Z

Pinging @elastic/es-security (Team:Security)

ywangd · 2021-08-17T01:31:27Z

x-pack/docs/en/rest-api/security/get-api-keys.asciidoc

    },
    {
-      "id": "api-key-id-2",
+      "id": "6wHJmcQpReKBa42EHV5SBw",


This change is not really related to the purpose of this PR. It's more of a bug fix of existing doc because this ID format is misleading.

ywangd · 2021-08-17T01:31:40Z

x-pack/docs/en/rest-api/security/get-api-keys.asciidoc

  "api_keys": [ <1>
    {
-      "id": "dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==", <2>
+      "id": "0GF5GXsBCXxz2eDxWwFN", <2>


Same as above.

tvernum · 2021-08-17T04:02:07Z

x-pack/docs/en/rest-api/security/query-api-key.asciidoc

+Note it only support a subset of the query types including
+<<query-dsl-match-all-query>>, <<query-dsl-bool-query>>,
+<<query-dsl-term-query>>, <<query-dsl-terms-query>>, <<query-dsl-ids-query>>,
+<<query-dsl-prefix-query>>, <<query-dsl-wildcard-query>>, <<query-dsl-range-query>>.


Should we have some comments about the fields that can be queried? Maybe a list, or at least an explanation of how people would work out what the fields are.

Thanks. I added a list to explain the available fields.

x-pack/docs/en/rest-api/security/query-api-key.asciidoc

tvernum · 2021-08-17T04:02:58Z

x-pack/docs/en/rest-api/security/query-api-key.asciidoc

+
+By default, you cannot page through more than 10,000 hits using the `from` and
+`size` parameters. To page through more hits, use the
+<<search-after,`search_after`>> parameter.


This is repeated from above. Is that intentional?

Yes it is indeed intentional. The same is repeated on the Search API doc page. The difference is that the two parameters, from and size, are further apart on the Search API page which makes the repitition more justifiable. I can consolidate them if you prefer.

tvernum · 2021-08-17T04:04:51Z

x-pack/docs/en/rest-api/security/query-api-key.asciidoc

+(Optional, array) <<search-after,Search after>> definition.
+
+NOTE: If the user only has `manage_own_api_key` privilege, this API returns
+only those API keys that are owned by the user.


I think we need to state the reverse as well.

If the user has manage_api_key or higher (including manage_security),
this API returns API keys that are owned by any user

(any user? all users?)

Good point. I added

On the other hand, if the user
has manage_api_key or greater privilege (including manage_security), this
API returns API keys regardless of their owners.

?

Co-authored-by: Tim Vernum <tim@adjective.org>

lockewritesdocs

Suggested some changes -- will push some changes to this branch for a definition list under the query parameter.

x-pack/docs/en/rest-api/security/query-api-key.asciidoc

lockewritesdocs · 2021-08-17T18:32:33Z

x-pack/docs/en/rest-api/security/query-api-key.asciidoc

+NOTE: If the user only has `manage_own_api_key` privilege, this API returns
+only those API keys that are owned by the user. On the other hand, if the user
+has `manage_api_key` or greater privilege (including `manage_security`), this
+API returns API keys regardless of their owners.


I think that this note belongs in the Prerequisites section where we mention which privileges are required to use the API.

I moved it under the prerequisites as a separate bullet point.

lockewritesdocs · 2021-08-17T18:52:57Z

x-pack/docs/en/rest-api/security/query-api-key.asciidoc

+<1> The list of API keys that were retrieved for this request.
+<2> Id for the API key
+<3> Name of the API key
+<4> Creation time for the API key in milliseconds
+<5> Optional expiration time for the API key in milliseconds
+<6> Invalidation status for the API key. If the key has been invalidated, it has
+a value of `true`. Otherwise, it is `false`.
+<7> Principal for which this API key was created
+<8> Realm name of the principal for which this API key was created
+<9> Metadata of the API key


I think that these callouts should be removed in favor of a proper definition list under the query parameter starting on line 44. I'll push changes to this branch with the formatted and updated definition list.

Co-authored-by: Adam Locke <adam.locke@elastic.co>

ywangd · 2021-08-18T00:31:13Z

@elasticmachine update branch

lockewritesdocs

👍 with the latest changes included

lockewritesdocs · 2021-08-18T19:29:31Z

@elasticmachine update branch

ywangd · 2021-08-18T22:44:41Z

@tvernum Because I merged the rest spec PR (#76238) too soon, our docs build is currently broken because the rest spec file points to an URL yet to be added by this PR. To fix the issue, I am going to merge this PR once the CI passes. Both @lockewritesdocs and I are OK with where it is now. But I am happy to raise a follow-up PR if you spot any issues (commenting and review are still allowed by the UI after merging). Sorry for the inconvenience. I'll manage it better next time.

ywangd · 2021-08-18T23:24:14Z

@elasticmachine run elasticsearch-ci/part-2-fips

The CI failure is irrelevant but seems legit, I raised #76689

elasticsearchmachine · 2021-08-19T00:12:33Z

💔 Backport failed

Status	Branch	Result
❌	7.15	Commit could not be cherrypicked due to conflicts

To backport manually run backport --upstream elastic/elasticsearch --pr 76521

This PR adds documentation for the new QueryApiKey API added in elastic#75335 and elastic#76144 Relates: elastic#71023

This PR adds documentation for the new QueryApiKey API added in #75335 and #76144 Relates: #71023

ywangd added >docs General docs changes :Security/Security Security issues without another label v7.15.0 v8.0.0-alpha1 labels Aug 14, 2021

elasticsearchmachine added the v8.0.0 label Aug 14, 2021

ywangd force-pushed the api-key-search-api-docs branch from f6277df to 559a8a5 Compare August 14, 2021 11:33

ywangd removed the v8.0.0-alpha1 label Aug 16, 2021

sethmlarson added the Team:Clients Meta label for clients team label Aug 16, 2021

API key search API - documentation

576fcde

ywangd force-pushed the api-key-search-api-docs branch from 559a8a5 to 576fcde Compare August 17, 2021 01:01

ywangd marked this pull request as ready for review August 17, 2021 01:29

elasticmachine added the Team:Docs Meta label for docs team label Aug 17, 2021

elasticmachine added the Team:Security Meta label for security team label Aug 17, 2021

ywangd requested review from lockewritesdocs and tvernum August 17, 2021 01:29

ywangd commented Aug 17, 2021

View reviewed changes

ywangd mentioned this pull request Aug 17, 2021

Search and Pagination for API keys #71023

Closed

5 tasks

tvernum reviewed Aug 17, 2021

View reviewed changes

ywangd and others added 2 commits August 17, 2021 16:35

Update x-pack/docs/en/rest-api/security/query-api-key.asciidoc

2b41cfd

Co-authored-by: Tim Vernum <tim@adjective.org>

address feedback

41a708a

lockewritesdocs reviewed Aug 17, 2021

View reviewed changes

ywangd and others added 2 commits August 18, 2021 10:13

Apply suggestions from code review

274810a

Co-authored-by: Adam Locke <adam.locke@elastic.co>

address feedback

55761b0

elasticmachine and others added 2 commits August 18, 2021 10:31

Merge branch 'master' into api-key-search-api-docs

7ce8063

add _sort example

4a8aa32

fix ref link

eba62eb

ywangd requested a review from tvernum August 18, 2021 05:08

Adam Locke added 2 commits August 18, 2021 11:15

Add definition list plus other editorial changes

3b35e2f

Update request body title

17628b7

lcawl mentioned this pull request Aug 18, 2021

[DOCS] Add stub docs for QueryApiKey API #76670

Merged

Merge branch 'master' into api-key-search-api-docs

fd31ca0

lockewritesdocs self-requested a review August 18, 2021 19:10

lockewritesdocs approved these changes Aug 18, 2021

View reviewed changes

Adam Locke added 2 commits August 18, 2021 15:20

Updating descriptions

1d03e77

Remove leftover markup from merging

b2d5962

elasticmachine and others added 2 commits August 19, 2021 05:29

Merge branch 'master' into api-key-search-api-docs

223b13a

tweaking

253791a

ywangd added the auto-backport Automatically create backport pull requests when merged label Aug 18, 2021

ywangd merged commit ccc9c35 into elastic:master Aug 19, 2021

ywangd added a commit to ywangd/elasticsearch that referenced this pull request Aug 19, 2021

Add docs for QueryApiKey API (elastic#76521)

926e09e

This PR adds documentation for the new QueryApiKey API added in elastic#75335 and elastic#76144 Relates: elastic#71023

ywangd added a commit to ywangd/elasticsearch that referenced this pull request Aug 19, 2021

Add docs for QueryApiKey API (elastic#76521)

7561df4

This PR adds documentation for the new QueryApiKey API added in elastic#75335 and elastic#76144 Relates: elastic#71023

elasticsearchmachine pushed a commit that referenced this pull request Aug 19, 2021

Add docs for QueryApiKey API (#76521) (#76691)

f54e617

This PR adds documentation for the new QueryApiKey API added in #75335 and #76144 Relates: #71023

elasticsearchmachine pushed a commit that referenced this pull request Aug 19, 2021

Add docs for QueryApiKey API (#76521) (#76690)

170a363

This PR adds documentation for the new QueryApiKey API added in #75335 and #76144 Relates: #71023

jakelandis added v8.0.0-alpha2 and removed v8.0.0 labels Sep 15, 2021

Conversation

ywangd commented Aug 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elasticmachine commented Aug 17, 2021

Uh oh!

elasticmachine commented Aug 17, 2021

Uh oh!

elasticmachine commented Aug 17, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ywangd Aug 17, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lockewritesdocs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ywangd commented Aug 18, 2021

Uh oh!

lockewritesdocs left a comment

Choose a reason for hiding this comment

Uh oh!

lockewritesdocs commented Aug 18, 2021

Uh oh!

ywangd commented Aug 18, 2021

Uh oh!

ywangd commented Aug 18, 2021

Uh oh!

elasticsearchmachine commented Aug 19, 2021

💔 Backport failed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

ywangd commented Aug 14, 2021 •

edited

Loading

ywangd Aug 17, 2021 •

edited

Loading