Merge pull request etcd-io#5734 from xiang90/learning

doc: move docs to learning

Documentation/docs.md

@@ -33,10 +33,11 @@ Administrators who need to create reliable and scalable key-value stores for the
 
 To learn more about the concepts and internals behind etcd, read the following pages:
 
- - Why etcd
- - Concepts
- - Internals
+ - Why etcd (TODO)
+ - [Understand data model][data_model]
+ - [Understand APIs][understand_apis]
  - [Glossary][glossary]
+ - Internals (TODO)
 
 ## Upgrading and compatibility
 
@@ -48,6 +49,7 @@ To learn more about the concepts and internals behind etcd, read the following p
 [api_grpc_gateway]: dev-guide/api_grpc_gateway.md
 [clustering]: op-guide/clustering.md
 [conf]: op-guide/configuration.md
+[data_model]: learning/data_model.md
 [demo]: demo.md
 [download_build]: dl_build.md
 [failures]: op-guide/failures.md
@@ -60,3 +62,4 @@ To learn more about the concepts and internals behind etcd, read the following p
 [security]: op-guide/security.md
 [v2_migration]: op-guide/v2-migration.md
 [container]: op-guide/container.md
+[understand_apis]: learning/api.md

Documentation/learning/api.md

@@ -0,0 +1,57 @@
+# etcd3 API
+
+NOTE: this doc is not finished!
+
+## Response Header
+
+All Responses from etcd API have a [response header][response_header] attached. The response header includes the metadata of the response.
+
+```proto
+message ResponseHeader {
+  uint64 cluster_id = 1;
+  uint64 member_id = 2;
+  int64 revision = 3;
+  uint64 raft_term = 4;
+}
+```
+
+* Cluster_ID - the ID of the cluster that generates the response
+* Member_ID - the ID of the member that generates the response
+* Revision - the revision of the key-value store when the response is generated
+* Raft_Term - the Raft term of the member when the response is generated
+
+An application may read the Cluster_ID (Member_ID) field to ensure it is communicating with the intended cluster (member).
+
+Applications can use the `Revision` to know the latest revision of the key-value store. This is especially useful when applications specify a historical revision to make time `travel query` and wishes to know the latest revision at the time of the request.
+
+Applications can use `Raft_Term` to detect when the cluster completes a new leader election.
+
+## 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.
+
+[kv-proto]: https://github.com/coreos/etcd/blob/master/mvcc/mvccpb/kv.proto
+[kv-service]: https://github.com/coreos/etcd/blob/master/etcdserver/etcdserverpb/rpc.proto
+[response_header]: https://github.com/coreos/etcd/blob/master/etcdserver/etcdserverpb/rpc.proto

Documentation/learning/api_guarantees.md

@@ -0,0 +1,63 @@
+# KV API Guarantees
+
+etcd is a consistent and durable key value store with mini-transaction(TODO: link to txn doc when we have it) support. The key value store is exposed through the KV APIs. etcd tries to ensure the strongest consistency and durability guarantees for a distributed system. This specification enumerates the KV API guarantees made by etcd.
+
+### APIs to consider
+
+* Read APIs
+    * range
+    * watch
+* Write APIs
+    * put
+    * delete
+* Combination (read-modify-write) APIs
+    * txn
+
+### etcd Specific Definitions
+
+#### operation completed
+
+An etcd operation is considered complete when it is committed through consensus, and therefore “executed” -- permanently stored -- by the etcd storage engine. The client knows an operation is completed when it receives a response from the etcd server. Note that the client may be uncertain about the status of an operation if it times out, or there is a network disruption between the client and the etcd member. etcd may also abort operations when there is a leader election. etcd does not send `abort` responses to  clients’ outstanding requests in this event.
+
+#### revision
+
+An etcd operation that modifies the key value store is assigned with a single increasing revision. A transaction operation might modifies the key value store multiple times, but only one revision is assigned. The revision attribute of a key value pair that modified by the operation has the same value as the revision of the operation. The revision can be used as a logical clock for key value store. A key value pair that has a larger revision is modified after a key value pair with a smaller revision. Two key value pairs that have the same revision are modified by an operation "concurrently".
+
+### Guarantees Provided
+
+#### Atomicity
+
+All API requests are atomic; an operation either completes entirely or not at all. For watch requests, all events generated by one operation will be in one watch response. Watch never observes partial events for a single operation.
+
+#### Consistency
+
+All API calls ensure [sequential consistency][seq_consistency], the strongest consistency guarantee available from distributed systems. No matter which etcd member server a client makes requests to, a client reads the same events in the same order. If two members complete the same number of operations, the state of the two members is consistent.
+
+For watch operations, etcd guarantees to return the same value for the same key across all members for the same revision. For range operations, etcd has a similar guarantee for [linearized][Linearizability] access; serialized access may be behind the quorum state, so that the later revision is not yet available.
+
+As with all distributed systems, it is impossible for etcd to ensure [strict consistency][strict_consistency]. etcd does not guarantee that it will return to a read the “most recent” value (as measured by a wall clock when a request is completed) available on any cluster member.
+
+#### Isolation
+
+etcd ensures [serializable isolation][serializable_isolation], which is the highest isolation level available in distributed systems. Read operations will never observe any intermediate data.
+
+#### Durability
+
+Any completed operations are durable. All accessible data is also durable data. A read will never return data that has not been made durable.
+
+#### Linearizability
+
+Linearizability (also known as Atomic Consistency or External Consistency) is a consistency level between strict consistency and sequential consistency. 
+
+For linearizability, suppose each operation receives a timestamp from a loosely synchronized global clock. Operations are linearized if and only if they always complete as though they were executed in a sequential order and each operation appears to complete in the order specified by the program. Likewise, if an operation’s timestamp precedes another, that operation must also precede the other operation in the sequence.
+
+For example, consider a client completing a write at time point 1 (*t1*). A client issuing a read at *t2* (for *t2* > *t1*) should receive a value at least as recent as the previous write, completed at *t1*. However, the read might actually complete only by *t3*, and the returned value, current at *t2* when the read began, might be "stale" by *t3*.
+
+etcd does not ensure linearizability for watch operations. Users are expected to verify the revision of watch responses to ensure correct ordering.
+
+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.
+
+[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