grpc-gatewayでRESTful APIを実装する

背景

何かしらの理由でRESTでAPIを実装しなくてはいけない時に、JSONを直接扱うのは面倒くさい。具体的には、JSONをデシリアライズして内部のデータ構造にマッピングする処理を書くのが面倒だ。というわけで、grpc-gatewayを使ってProtocol Buffersを定義するだけでREST APIを実装できないかを検討してみた。

gRPCとは

gRPCはサービスの定義やリモートから呼び出されるメソッドの詳細な定義(引数や戻り値)をProtocol Buffers(以降Protobuf)を用いて定義する。つまりgRPCではProtobufがIDL(Interface Definition Language)として使われていて、protocというコマンドからProtobuf上のサービス・メソッド定義から各プログラミング言語のソースコードが生成できる。

grpc-gatewayとは

grpc-gatewayはprotocのプラグインとして実装されている。Protobufで定義されたサービスやメソッドの定義から、RESTful JSON APIをgRPCに変換するReverseProxyサーバーのソースコードを生成する。

例えば、以下のような定義を.protoファイルに書いておくと、 GET /users/{id} のRESTful APIのendpointを受け付けるサーバーのコードが生成される。

service Users {
    rpc GetUser(GetUserRequest) returns (User) {
        option (google.api.http) = {
            get: "/v1/users/{id}"
        };
    }
}

message GetUserRequest {
    string id = 1;
}

message User {
    string id = 1;
    string name = 2;
    string real_name = 3;
}

Protocol BuffersでAPIを定義してみる

では実際にprotoファイルに以下のAPIを定義してみる。RESTのendpointやgRPCのメソッドの命名についてはGoogleが公開しているAPIのスタンダードに沿っている。これはかなり参考になるドキュメントなので一通り読んでおくと良いと思う。Googleが提供しているAPIの70%以上はこのスタンダードに沿っているらしい。

API

REST endpoint

gRPC method

ユーザーの一覧取得

GET /v1/users

ListUsers

ユーザーの単体取得

GET /v1/users/{id}

GetUser

ユーザーの作成

POST /v1/users

CreateUser

ユーザーの更新

PUT /v1/users/{id}

UpdateUser

ユーザーの削除

DELETE /v1/users/{id}

DeleteUser

サンプルのProtobufファイル users.proto

protocコマンドでgoのコードを生成

https://github.com/oinume/grpc-sample のリポジトリを $GOPATH/src/github.com/oinume 配下にcloneすることで、makeとgoがインストールされていば以下のコマンドで.protoファイルからgoのソースが生成できる。(ソースは proto-gen ディレクトリに生成される)

$ make setup
$ make proto/go

grpc-gatewayのサーバーを起動

最後に、サーバーの実装をビルドしてgrpc-gatewayのサーバーを起動してみよう。

ビルド

$ make
go build -o bin/grpc-sample github.com/oinume/grpc-sample/cmd

サーバーの起動

$ ./bin/grpc-sample

Listening on 5000
Starting gRPC server on 5001

5000番ポートでHTTPをLISTENする。バックエンドのgRPCサーバーは5001番ポートでLISTEN。

curlでREST APIを呼び出す

サーバーを立ち上げたら実際にcurlコマンドでREST APIのendpointにAPIリクエストを投げてみよう。例えば、新しいユーザーを作成するAPIは以下のコマンドを実行する。

$ curl -v -X POST -d '{"name": "oinume", "real_name": "kazuhiro oinuma"}' http://localhost:5000/v1/users | jq .

{
  "id": "12345",
  "name": "oinume",
  "real_name": "kazuhiro oinuma"
}

READMEに各APIのcurlでの呼び出し方法も書いてあるので参考にして欲しい。ちなみにサーバーの実装はただのモックなので、実際にどこかのDBにデータができるということはない。

サーバーの実装

https://github.com/oinume/grpc-sample/blob/master/server/server.go

これが今回のAPIサーバーのgRPCでの実装部分なのだが、あくまで生成されたgRPCのinterfaceを満たすようにGoのメソッドを定義すれば良い。メソッドの引数であるリクエストと戻り値のレスポンスのデータはProtobufで定義されたものがGoの構造体になっているので、そのまま使えば良い。

あとは、以下のようにgrpc-gatewayのためのおまじない的なコードを少し書くだけでRESTful API serverが出来上がる。

https://github.com/oinume/grpc-sample/blob/master/cmd/main.go#L64-L73

まとめ

このようにgrpc-gatewayを使うことで、RESTful APIを定義する上で手間だったJSONの変換部分を手で書く必要がなくなった。たくさんのAPIを実装するプロジェクトでは、ProtobufでAPI定義を書く必要が発生するとはいえ、手作業でJSON<->structの変換処理を書かなくて済むことが大きなメリットになるはずなので、興味がある人はぜひ試してみて欲しい。

背景