Update API documentation #1070

ronaldngounou · 2025-10-11T08:46:11Z

Key changes:

Update Line 168 to address issue Documentation for Range should state that revision filtering does not affect returned count. #1063

`count` - the actual number of keys within the range when requested. 
Unlike Kvs, it is unaffected by limits and filters (e.g., Min/Max, Create/Modify, Revisions) 
and reflect the full count within the specified range.

Improvement to the current documentation by reflecting the latest changes from uptream code base to ensure it remains consistency and similar issues are not occuring. Some information were outdated.
Source of my changes: https://github.com/etcd-io/etcd/blob/main/api/etcdserverpb/rpc.proto

Testing

npm run check-links
npm run build
npm run serve

k8s-ci-robot · 2025-10-11T08:46:16Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: ronaldngounou
Once this PR has been reviewed and has the lgtm label, please assign jberkus for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

content/en/docs/v3.6/learning/api.md

jberkus

Overall a nice improvement to this doc, just need some follow-up cleanup. Thanks!

content/en/docs/v3.6/learning/api.md

- Revision field doesn't affect count - Solves Issue etcd-io#1063 - Update API documentation for consistency with upstream code reference: https://github.com/etcd-io/etcd/blob/main/api/etcdserverpb/rpc.proto Signed-off-by: Ronald Ngounou <[email protected]>

wendy-ha18 · 2025-10-29T00:38:48Z

cc @wendy-ha18 for reviewing.

ronaldngounou · 2025-11-02T21:15:40Z

Reminder on the review @wendy-ha18 @jberkus

wendy-ha18 · 2025-11-18T08:49:54Z

content/en/docs/v3.6/learning/api.md

-* Max_Mod_Revision - the upper bound for key mod revisions; filters out greater mod revisions.
-* Min_Create_Revision - the lower bound for key create revisions; filters out lesser create revisions.
-* Max_Create_Revision - the upper bound for key create revisions; filters out greater create revisions.
+* `key`, `range_end` - The key range to fetch.


Suggested change

* `key`, `range_end` - The key range to fetch.

* `key`, `range_end` - the key range to fetch.

keep the format consistent.

wendy-ha18 · 2025-11-18T09:16:39Z

content/en/docs/v3.6/learning/api.md

-* Type - The kind of event. A PUT type indicates new data has been stored to the key. A DELETE indicates the key was deleted.
-* KV - The KeyValue associated with the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE event contains the deleted key with its modification revision set to the revision of deletion.
-* Prev_KV - The key-value pair for the key from the revision immediately before the event. To save bandwidth, it is only filled out if the watch has explicitly enabled it.
+* `type` - The kind of event. A PUT type indicates new data has been stored to the key. A DELETE indicates the key was deleted.


Suggested change

* `type` - The kind of event. A PUT type indicates new data has been stored to the key. A DELETE indicates the key was deleted.

* `type` - the kind of event. A PUT type indicates new data has been stored to the key. A DELETE indicates the key was deleted.

wendy-ha18 · 2025-11-18T09:16:49Z

content/en/docs/v3.6/learning/api.md

-* KV - The KeyValue associated with the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE event contains the deleted key with its modification revision set to the revision of deletion.
-* Prev_KV - The key-value pair for the key from the revision immediately before the event. To save bandwidth, it is only filled out if the watch has explicitly enabled it.
+* `type` - The kind of event. A PUT type indicates new data has been stored to the key. A DELETE indicates the key was deleted.
+* `kv` - The KeyValue associated with the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE event contains the deleted key with its modification revision set to the revision of deletion.


Suggested change

* `kv` - The KeyValue associated with the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE event contains the deleted key with its modification revision set to the revision of deletion.

* `kv` - the KeyValue associated with the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE event contains the deleted key with its modification revision set to the revision of deletion.

wendy-ha18 · 2025-11-18T09:17:31Z

content/en/docs/v3.6/learning/api.md

-* Prev_KV - The key-value pair for the key from the revision immediately before the event. To save bandwidth, it is only filled out if the watch has explicitly enabled it.
+* `type` - The kind of event. A PUT type indicates new data has been stored to the key. A DELETE indicates the key was deleted.
+* `kv` - The KeyValue associated with the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE event contains the deleted key with its modification revision set to the revision of deletion.
+* `prev_kv` - The key-value pair for the key from the revision immediately before the event. To save bandwidth, it is only filled out if the watch has explicitly enabled it.


Suggested change

* `prev_kv` - The key-value pair for the key from the revision immediately before the event. To save bandwidth, it is only filled out if the watch has explicitly enabled it.

* `prev_kv` - the key-value pair for the key from the revision immediately before the event. To save bandwidth, it is only filled out if the watch has explicitly enabled it.

wendy-ha18 · 2025-11-18T09:17:47Z

content/en/docs/v3.6/learning/api.md

-* Progress_Notify - When set, the watch will periodically receive a WatchResponse with no events, if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server decides how often to send notifications based on current server load.
-* Filters - A list of event types to filter away at server side.
-* Prev_Kv - When set, the watch receives the key-value data from before the event happens. This is useful for knowing what data has been overwritten.
+* `key`, `range_end` - The key range to watch.


Suggested change

* `key`, `range_end` - The key range to watch.

* `key`, `range_end` - the key range to watch.

wendy-ha18 · 2025-11-18T09:17:55Z

content/en/docs/v3.6/learning/api.md

-* Filters - A list of event types to filter away at server side.
-* Prev_Kv - When set, the watch receives the key-value data from before the event happens. This is useful for knowing what data has been overwritten.
+* `key`, `range_end` - The key range to watch.
+* `start_revision` - An optional revision for where to inclusively begin watching. If not given, it will stream events following the revision of the watch creation response header revision. The entire available event history can be watched starting from the last compaction revision.


Suggested change

* `start_revision` - An optional revision for where to inclusively begin watching. If not given, it will stream events following the revision of the watch creation response header revision. The entire available event history can be watched starting from the last compaction revision.

* `start_revision` - an optional revision for where to inclusively begin watching. If not given, it will stream events following the revision of the watch creation response header revision. The entire available event history can be watched starting from the last compaction revision.

wendy-ha18 · 2025-11-18T09:18:04Z

content/en/docs/v3.6/learning/api.md

-* Prev_Kv - When set, the watch receives the key-value data from before the event happens. This is useful for knowing what data has been overwritten.
+* `key`, `range_end` - The key range to watch.
+* `start_revision` - An optional revision for where to inclusively begin watching. If not given, it will stream events following the revision of the watch creation response header revision. The entire available event history can be watched starting from the last compaction revision.
+* `progress_notify` - When set, the watch will periodically receive a WatchResponse with no events, if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server decides how often to send notifications based on current server load.


Suggested change

* `progress_notify` - When set, the watch will periodically receive a WatchResponse with no events, if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server decides how often to send notifications based on current server load.

* `progress_notify` - when set, the watch will periodically receive a WatchResponse with no events, if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server decides how often to send notifications based on current server load.

wendy-ha18 · 2025-11-18T09:18:13Z

content/en/docs/v3.6/learning/api.md

+* `key`, `range_end` - The key range to watch.
+* `start_revision` - An optional revision for where to inclusively begin watching. If not given, it will stream events following the revision of the watch creation response header revision. The entire available event history can be watched starting from the last compaction revision.
+* `progress_notify` - When set, the watch will periodically receive a WatchResponse with no events, if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server decides how often to send notifications based on current server load.
+* `filters` - A list of event types to filter away at server side.


Suggested change

* `filters` - A list of event types to filter away at server side.

* `filters` - a list of event types to filter away at server side.

wendy-ha18 · 2025-11-18T09:18:22Z

content/en/docs/v3.6/learning/api.md

+* `start_revision` - An optional revision for where to inclusively begin watching. If not given, it will stream events following the revision of the watch creation response header revision. The entire available event history can be watched starting from the last compaction revision.
+* `progress_notify` - When set, the watch will periodically receive a WatchResponse with no events, if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server decides how often to send notifications based on current server load.
+* `filters` - A list of event types to filter away at server side.
+* `prev_kv` - When set, the watch receives the key-value data from before the event happens. This is useful for knowing what data has been overwritten.


Suggested change

* `prev_kv` - When set, the watch receives the key-value data from before the event happens. This is useful for knowing what data has been overwritten.

* `prev_kv` - when set, the watch receives the key-value data from before the event happens. This is useful for knowing what data has been overwritten.

wendy-ha18 · 2025-11-18T09:21:10Z

content/en/docs/v3.6/learning/api.md

+* `ID` - the lease that was refreshed with a new TTL.
+* `TTL` - the new time-to-live, in seconds, that the lease has remaining.

 [watch-api-guarantees]: ../api_guarantees/#watch-apis


This relative link is currently broken. Could you please help to update it as well? Thank you

The gRPC API listing link is also error.

website/content/en/docs/v3.6/learning/api.md

Line 485 in a7d34ed

[grpc-api]: ../../dev-guide/api_reference_v3/

wendy-ha18 · 2025-11-18T09:23:57Z

I only had a few small comments, but the overall of this PR is LGTM.
We could merge it after the format and broken links being fixed. Thank Ronal!

k8s-ci-robot added the size/L label Oct 11, 2025

ronaldngounou force-pushed the issue1063-revision_filtering branch from 10a8a58 to ea616b8 Compare October 11, 2025 08:55

ronaldngounou commented Oct 11, 2025

View reviewed changes

content/en/docs/v3.6/learning/api.md Outdated Show resolved Hide resolved

ronaldngounou changed the title ~~Update API documentation: evision field doesn't affect count~~ Update API documentation Oct 11, 2025

jberkus requested changes Oct 18, 2025

View reviewed changes

ronaldngounou force-pushed the issue1063-revision_filtering branch from ea616b8 to 1667b38 Compare October 19, 2025 04:55

Update API documentation

a7d34ed

- Revision field doesn't affect count - Solves Issue etcd-io#1063 - Update API documentation for consistency with upstream code reference: https://github.com/etcd-io/etcd/blob/main/api/etcdserverpb/rpc.proto Signed-off-by: Ronald Ngounou <[email protected]>

ronaldngounou force-pushed the issue1063-revision_filtering branch from 1667b38 to a7d34ed Compare October 19, 2025 05:02

ronaldngounou requested a review from jberkus October 19, 2025 05:04

wendy-ha18 reviewed Nov 18, 2025

View reviewed changes

	* `key`, `range_end` - The key range to fetch.
	* `key`, `range_end` - the key range to fetch.

	* `type` - The kind of event. A PUT type indicates new data has been stored to the key. A DELETE indicates the key was deleted.
	* `type` - the kind of event. A PUT type indicates new data has been stored to the key. A DELETE indicates the key was deleted.

	* `kv` - The KeyValue associated with the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE event contains the deleted key with its modification revision set to the revision of deletion.
	* `kv` - the KeyValue associated with the event. A PUT event contains current kv pair. A PUT event with kv.Version=1 indicates the creation of a key. A DELETE event contains the deleted key with its modification revision set to the revision of deletion.

	* `prev_kv` - The key-value pair for the key from the revision immediately before the event. To save bandwidth, it is only filled out if the watch has explicitly enabled it.
	* `prev_kv` - the key-value pair for the key from the revision immediately before the event. To save bandwidth, it is only filled out if the watch has explicitly enabled it.

	* `start_revision` - An optional revision for where to inclusively begin watching. If not given, it will stream events following the revision of the watch creation response header revision. The entire available event history can be watched starting from the last compaction revision.
	* `start_revision` - an optional revision for where to inclusively begin watching. If not given, it will stream events following the revision of the watch creation response header revision. The entire available event history can be watched starting from the last compaction revision.

	* `progress_notify` - When set, the watch will periodically receive a WatchResponse with no events, if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server decides how often to send notifications based on current server load.
	* `progress_notify` - when set, the watch will periodically receive a WatchResponse with no events, if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The etcd server decides how often to send notifications based on current server load.

	* `filters` - A list of event types to filter away at server side.
	* `filters` - a list of event types to filter away at server side.

	* `prev_kv` - When set, the watch receives the key-value data from before the event happens. This is useful for knowing what data has been overwritten.
	* `prev_kv` - when set, the watch receives the key-value data from before the event happens. This is useful for knowing what data has been overwritten.

Update API documentation #1070

Are you sure you want to change the base?

Update API documentation #1070

Uh oh!

Conversation

ronaldngounou commented Oct 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key changes:

Testing

Uh oh!

k8s-ci-robot commented Oct 11, 2025

Uh oh!

Uh oh!

jberkus left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wendy-ha18 commented Oct 29, 2025

Uh oh!

ronaldngounou commented Nov 2, 2025

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!

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!

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!

wendy-ha18 commented Nov 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ronaldngounou commented Oct 11, 2025 •

edited

Loading