diff --git a/Documentation/api_v3.md b/Documentation/api_v3.md index 21bc61c9b..b527ea9bd 100644 --- a/Documentation/api_v3.md +++ b/Documentation/api_v3.md @@ -1,6 +1,33 @@ # etcd3 API -TODO: API doc +TODO: finish API doc + +## Key-Value API + +Key-Value API is used to manipulate key-value pairs stored inside etcd. The key-value API is defined as a [gRPC service][kv-service]. The Key-Value pair is defined as structured data in [protobuf format][kv-proto]. + +### Key-Value Pair + +A key-value pair is the smallest unit that the key-value API can manipulate. Each key-value pair has a number of fields: + +```protobuf +message KeyValue { + bytes key = 1; + int64 create_revision = 2; + int64 mod_revision = 3; + int64 version = 4; + bytes value = 5; + int64 lease = 6; +} +``` + +* Key - key in bytes. An empty key is not allowed. +* Value - value in bytes. +* Version - version is the version of the key. A deletion resets the version to zero and any modification of the key increases its version. +* Create_Revision - revision of the last creation on the key. +* Mod_Revision - revision of the last modification on the key. +* Lease - the ID of the lease attached to the key. If lease is 0, then no lease is attached to the key. + ## Data Model @@ -83,10 +110,12 @@ etcd does not ensure linearizability for watch operations. Users are expected to etcd ensures linearizability for all other operations by default. Linearizability comes with a cost, however, because linearized requests must go through the Raft consensus process. To obtain lower latencies and higher throughput for read requests, clients can configure a request’s consistency mode to `serializable`, which may access stale data with respect to quorum, but removes the performance penalty of linearized accesses' reliance on live consensus. -[persistent-ds]: [https://en.wikipedia.org/wiki/Persistent_data_structure] -[btree]: [https://en.wikipedia.org/wiki/B-tree] -[b+tree]: [https://en.wikipedia.org/wiki/B%2B_tree] -[seq_consistency]: [https://en.wikipedia.org/wiki/Consistency_model#Sequential_consistency] -[strict_consistency]: [https://en.wikipedia.org/wiki/Consistency_model#Strict_consistency] -[serializable_isolation]: [https://en.wikipedia.org/wiki/Isolation_(database_systems)#Serializable] -[Linearizability]: [#Linearizability] +[persistent-ds]: https://en.wikipedia.org/wiki/Persistent_data_structure +[btree]: https://en.wikipedia.org/wiki/B-tree +[b+tree]: https://en.wikipedia.org/wiki/B%2B_tree +[seq_consistency]: https://en.wikipedia.org/wiki/Consistency_model#Sequential_consistency +[strict_consistency]: https://en.wikipedia.org/wiki/Consistency_model#Strict_consistency +[serializable_isolation]: https://en.wikipedia.org/wiki/Isolation_(database_systems)#Serializable +[Linearizability]: #Linearizability +[kv-proto]: https://github.com/coreos/etcd/blob/master/storage/storagepb/kv.proto +[kv-service]: https://github.com/coreos/etcd/blob/master/etcdserver/etcdserverpb/rpc.proto