From 09e5db5a46a4fb9c1f40f878472f4c04f8302321 Mon Sep 17 00:00:00 2001
From: Gyu-Ho Lee <gyuhox@gmail.com>
Date: Fri, 17 Jun 2016 15:01:33 -0700
Subject: [PATCH] Documentation: add grpc-gateway doc

---
 Documentation/dev-guide/api_grpc_gateway.md | 38 +++++++++++++++++++++
 Documentation/docs.md                       |  2 ++
 2 files changed, 40 insertions(+)
 create mode 100644 Documentation/dev-guide/api_grpc_gateway.md

diff --git a/Documentation/dev-guide/api_grpc_gateway.md b/Documentation/dev-guide/api_grpc_gateway.md
new file mode 100644
index 000000000..4028a6f71
--- /dev/null
+++ b/Documentation/dev-guide/api_grpc_gateway.md
@@ -0,0 +1,38 @@
+
+## Why grpc-gateway
+
+etcd v3 uses [gRPC][grpc] for its messaging protocol. The etcd project includes a gRPC-based [Go client][go-client] and a command line utility, [etcdctl][etcdctl], for communicating with an etcd cluster through gRPC. For languages with no gRPC support, etcd provides a JSON [grpc-gateway][grpc-gateway]. This gateway serves a RESTful proxy that translates HTTP/JSON requests into gRPC messages.
+
+
+## Using grpc-gateway
+
+The gateway accepts a [JSON mapping][json-mapping] for etcd's [protocol buffer][api-ref] message definitions. Note that `key` and `value` fields are defined as byte arrays and therefore must be base64 encoded in JSON.
+
+```bash
+<<COMMENT
+https://www.base64encode.org/
+foo is 'Zm9v' in Base64
+bar is 'YmFy'
+COMMENT
+
+curl -L http://localhost:2379/v3alpha/kv/put \
+	-X POST -d '{"key": "Zm9v", "value": "YmFy"}'
+
+curl -L http://localhost:2379/v3alpha/kv/range \
+	-X POST -d '{"key": "Zm9v"}'
+```
+
+
+## Swagger
+
+Generated [Swapper][swagger] API definitions can be found at [rpc.swagger.json][swagger-doc].
+
+[api-ref]: ./api_reference_v3.md
+[go-client]: https://github.com/coreos/etcd/tree/master/clientv3
+[etcdctl]: https://github.com/coreos/etcd/tree/master/etcdctl
+[grpc]: http://www.grpc.io/
+[grpc-gateway]: https://github.com/gengo/grpc-gateway
+[json-mapping]: https://developers.google.com/protocol-buffers/docs/proto3#json
+[swagger]: http://swagger.io/
+[swagger-doc]: apispec/swagger/rpc.swagger.json
+
diff --git a/Documentation/docs.md b/Documentation/docs.md
index 07dbfa863..82a46ed11 100644
--- a/Documentation/docs.md
+++ b/Documentation/docs.md
@@ -13,6 +13,7 @@ The easiest way to get started using etcd as a distributed key-value store for y
  - [Setting up local clusters][local_cluster]
  - [Interacting with etcd][interacting]
  - [API references][api_ref]
+ - [gRPC gateway][api_grpc_gateway]
 
 ## Operating etcd clusters
 
@@ -44,6 +45,7 @@ To learn more about the concepts and internals behind etcd, read the following p
 ## Troubleshooting
 
 [api_ref]: dev-guide/api_reference_v3.md
+[api_grpc_gateway]: dev-guide/api_grpc_gateway.md
 [clustering]: op-guide/clustering.md
 [conf]: op-guide/configuration.md
 [demo]: demo.md