go.etcd.io/etcd@v3.3.27+incompatible/Documentation/dev-guide/api_grpc_gateway.md (about) 1 --- 2 title: Why gRPC gateway 3 --- 4 5 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. 6 7 ## Using gRPC gateway 8 9 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. The following examples use `curl`, but any HTTP/JSON client should work all the same. 10 11 ### Notes 12 13 gRPC gateway endpoint has changed since etcd v3.3: 14 15 - etcd v3.2 or before uses only `[CLIENT-URL]/v3alpha/*`. 16 - etcd v3.3 uses `[CLIENT-URL]/v3beta/*` while keeping `[CLIENT-URL]/v3alpha/*`. 17 - etcd v3.4 uses `[CLIENT-URL]/v3/*` while keeping `[CLIENT-URL]/v3beta/*`. 18 - **`[CLIENT-URL]/v3alpha/*` is deprecated**. 19 - etcd v3.5 or later uses only `[CLIENT-URL]/v3/*`. 20 - **`[CLIENT-URL]/v3beta/*` is deprecated**. 21 22 gRPC-gateway does not support authentication using TLS Common Name. 23 24 ### Put and get keys 25 26 Use the `/v3/kv/range` and `/v3/kv/put` services to read and write keys: 27 28 ```bash 29 <<COMMENT 30 https://www.base64encode.org/ 31 foo is 'Zm9v' in Base64 32 bar is 'YmFy' 33 COMMENT 34 35 curl -L http://localhost:2379/v3/kv/put \ 36 -X POST -d '{"key": "Zm9v", "value": "YmFy"}' 37 # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"}} 38 39 curl -L http://localhost:2379/v3/kv/range \ 40 -X POST -d '{"key": "Zm9v"}' 41 # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"} 42 43 # get all keys prefixed with "foo" 44 curl -L http://localhost:2379/v3/kv/range \ 45 -X POST -d '{"key": "Zm9v", "range_end": "Zm9w"}' 46 # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"3"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}],"count":"1"} 47 ``` 48 49 ### Watch keys 50 51 Use the `/v3/watch` service to watch keys: 52 53 ```bash 54 curl -N http://localhost:2379/v3/watch \ 55 -X POST -d '{"create_request": {"key":"Zm9v"} }' & 56 # {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"1","raft_term":"2"},"created":true}} 57 58 curl -L http://localhost:2379/v3/kv/put \ 59 -X POST -d '{"key": "Zm9v", "value": "YmFy"}' >/dev/null 2>&1 60 # {"result":{"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"2","raft_term":"2"},"events":[{"kv":{"key":"Zm9v","create_revision":"2","mod_revision":"2","version":"1","value":"YmFy"}}]}} 61 ``` 62 63 ### Transactions 64 65 Issue a transaction with `/v3/kv/txn`: 66 67 ```bash 68 # target CREATE 69 curl -L http://localhost:2379/v3/kv/txn \ 70 -X POST \ 71 -d '{"compare":[{"target":"CREATE","key":"Zm9v","createRevision":"2"}],"success":[{"requestPut":{"key":"Zm9v","value":"YmFy"}}]}' 72 # {"header":{"cluster_id":"12585971608760269493","member_id":"13847567121247652255","revision":"3","raft_term":"2"},"succeeded":true,"responses":[{"response_put":{"header":{"revision":"3"}}}]} 73 ``` 74 75 ```bash 76 # target VERSION 77 curl -L http://localhost:2379/v3/kv/txn \ 78 -X POST \ 79 -d '{"compare":[{"version":"4","result":"EQUAL","target":"VERSION","key":"Zm9v"}],"success":[{"requestRange":{"key":"Zm9v"}}]}' 80 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"6","raft_term":"3"},"succeeded":true,"responses":[{"response_range":{"header":{"revision":"6"},"kvs":[{"key":"Zm9v","create_revision":"2","mod_revision":"6","version":"4","value":"YmF6"}],"count":"1"}}]} 81 ``` 82 83 ### Authentication 84 85 Set up authentication with the `/v3/auth` service: 86 87 ```bash 88 # create root user 89 curl -L http://localhost:2379/v3/auth/user/add \ 90 -X POST -d '{"name": "root", "password": "pass"}' 91 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}} 92 93 # create root role 94 curl -L http://localhost:2379/v3/auth/role/add \ 95 -X POST -d '{"name": "root"}' 96 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}} 97 98 # grant root role 99 curl -L http://localhost:2379/v3/auth/user/grant \ 100 -X POST -d '{"user": "root", "role": "root"}' 101 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}} 102 103 # enable auth 104 curl -L http://localhost:2379/v3/auth/enable -X POST -d '{}' 105 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"}} 106 ``` 107 108 Authenticate with etcd for an authentication token using `/v3/auth/authenticate`: 109 110 ```bash 111 # get the auth token for the root user 112 curl -L http://localhost:2379/v3/auth/authenticate \ 113 -X POST -d '{"name": "root", "password": "pass"}' 114 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"1","raft_term":"2"},"token":"sssvIpwfnLAcWAQH.9"} 115 ``` 116 117 Set the `Authorization` header to the authentication token to fetch a key using authentication credentials: 118 119 ```bash 120 curl -L http://localhost:2379/v3/kv/put \ 121 -H 'Authorization : sssvIpwfnLAcWAQH.9' \ 122 -X POST -d '{"key": "Zm9v", "value": "YmFy"}' 123 # {"header":{"cluster_id":"14841639068965178418","member_id":"10276657743932975437","revision":"2","raft_term":"2"}} 124 ``` 125 126 ## Swagger 127 128 Generated [Swagger][swagger] API definitions can be found at [rpc.swagger.json][swagger-doc]. 129 130 [api-ref]: ./api_reference_v3.md 131 [go-client]: https://github.com/coreos/etcd/tree/master/clientv3 132 [etcdctl]: https://github.com/coreos/etcd/tree/master/etcdctl 133 [grpc]: https://www.grpc.io/ 134 [grpc-gateway]: https://github.com/grpc-ecosystem/grpc-gateway 135 [json-mapping]: https://developers.google.com/protocol-buffers/docs/proto3#json 136 [swagger]: http://swagger.io/ 137 [swagger-doc]: apispec/swagger/rpc.swagger.json