Skip to content
A protoc plugin that generates graphql execution code from Protocol Buffers.
Go Shell Makefile
Branch: master
Clone or download

Latest commit

Latest commit 96b1dd5 Mar 18, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci move release script to misc Mar 15, 2020
example add stop task Mar 12, 2020
graphql put allocaed extension number Mar 17, 2020
include/graphql put allocaed extension number Mar 17, 2020
misc move release script to misc Mar 15, 2020
protoc-gen-graphql example and README Mar 12, 2020
runtime add example with docker Mar 12, 2020
.gitignore add example with docker Mar 12, 2020
.golangci.yml add lint file Mar 12, 2020
LICENSE Initial commit Jan 30, 2020
Makefile change order Mar 12, 2020
README.md Update README.md Mar 17, 2020
go.mod fix graphql-go problem Mar 12, 2020
go.sum modify template, generator Mar 5, 2020

README.md

grpc-graphql-gateway

CircleCI

grpc-graphql-gateway is a protoc plugin that generates graphql execution code from Protocol Buffers.

image

Motivation

On API development, frequently we choose some IDL, in order to manage API definitions from a file. Considering two of IDL -- GraphQL and Protocol Buffers (for gRPC) -- these have positive point respectively:

  • GraphQL -- Can put together multiple resources getting into one HTTP request, appropriate for BFF
  • gRPC -- Easy syntax in Protocol Buffers, and easy to implement API server using HTTP/2

But sometimes it's hard to maintain both GraphQL and Protocol Buffers, so we created this plugin in order to generate GraphQL Schema from Protocol Buffers.

This project much refers to grpc-gateway how to generate a file, provide a plugin. many thanks!

Installation

Get plugin binary

Get protoc-gen-graphql binary from releases page and set $PATH to be executable.

Or, simply get the latest one:

go get github.com/ysugimoto/grpc-graphql-gateway/protoc-gen-graphql/...

Then the binary will place in $GOBIN.

Get protobuf file

Get include/graphql.proto from this repository and put it into your project under the protobuf files.

git submodule add https://github.com/ysugimoto/grpc-graphql-gateway.git grpc-graphql-gateway
## Or another way...

Usage

Please replace [your/project] section to your appropriate project.

Write Protocol Buffers

Declare gRPC service with protobuf using grpc-graphql-gateway options. This example has two RPCs that names SayHello and SayGoodbye:

// greeter.proto
syntax = "proto3";

import "graphql.proto";

service Greeter {
  // gRPC service information
  option (graphql.service) = {
    host: "localhost:50051"
    insecure: true
  };

  rpc SayHello (HelloRequest) returns (HelloReply) {
    // Here is plugin definition
    option (graphql.schema) = {
      type: QUERY   // decleare as Query
      name: "hello" // query name
    };
  }

  rpc SayGoodbye (GoodbyeRequest) returns (GoodbyeReply) {
    // Here is plugin definition
    option (graphql.schema) = {
      type: QUERY     // decleare as Query
      name: "goodbye" // query name
    };
  }
}

message HelloRequest {
  // Below line means the "name" field is required in GraphQL argument
  string name = 1 [(graphql.field) = {required: true}];
}

message HelloReply {
  string message = 1;
}

message GoodbyeRequest {
  // Below line means the "name" field is required in GraphQL argument
  string name = 1 [(graphql.field) = {required: true}];
}

message GoodbyeReply {
  string message = 1;
}

Compile to Go code

Compile protobuf file with the plugin:

protoc \
  -I. \
  --go_out=plugins=grpc:./greeter \
  --graphql_out=./greeter \
  greeter.proto

Then you can see greeter/greeter.pb.go and greeter/greeter.graphql.go.

Implement service

For example, gRPC service will be:

// service/main.go
package main

import (
    "context"
    "fmt"
    "net"
    "log"

    "github.com/[your/project]/greeter"
    "google.golang.org/grpc"
)

type Server struct{}

func (s *Server) SayHello(ctx context.Context, req *greeter.HelloRequest) (*greeter.HelloReply, error) {
	return &greeter.HelloReply{
		Message: fmt.Sprintf("Hello, %s!", req.GetName()),
	}, nil
}

func (s *Server) SayGoodbye(ctx context.Context, req *greeter.GoodbyeRequest) (*greeter.GoodbyeReply, error) {
	return &greeter.GoodbyeReply{
		Message: fmt.Sprintf("Good-bye, %s!", req.GetName()),
	}, nil
}

func main() {
	conn, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	server := grpc.NewServer()
	greeter.RegisterGreeterServer(server, &Server{})
	server.Serve(conn)
}

Then let's start service:

go run service/main.go

The gRPC service will start on localhost:50051.

Next, GraphQL gateway service should be:

// gateway/main.go
package main

import (
    "log"

    "net/http"

    "github.com/[your/project]/greeter"
    "github.com/ysugimoto/grpc-graphql-gateway/runtime"
)

func main() {
    mux := runtime.NewServeMux()

    if err := greeter.RegisterGreeterGraphql(mux); err != nil {
        log.Fatalln(err)
    }
    http.Handle("/graphql", mux)
    log.Fatalln(http.ListenAndServe(":8888", nil))
}

Then let's start gateway:

go run gateway/main.go

The GraphQL gateway will start on localhost:8888

Send request via the gateway

Now you can access gRPC service via GraphQL gateway!

curl -g "http://localhost:8888/graphql" -d '
{
  hello(name: "GraphQL Gateway") {
    message
  }
}'
#=> {"data":{"hello":{"message":"Hello, GraphQL Gateway!"}}}

You can also send request via POST method with operation name like:

curl -XPOST "http://localhost:8888/graphql" -d '
query greeting($name: String = "GraphQL Gateway") {
  hello(name: $name) {
    message
  }
  goodbye(name: $name) {
    message
  }
}'
#=> {"data":{"goodbye":{"message":"Good-bye, GraphQL Gateway!"},"hello":{"message":"Hello, GraphQL Gateway!"}}}

This is the most simplest way :-)

Resources

To learn more, please see the following resources:

  • graphql.proto Plugin option definition. See a comment section for custom usage (e.g mutation).
  • example/greeter Files of above usage.
  • example/starwars Common implementation for GraphQL explanation, the StarWars API example

This plugin generates graphql execution code using graphql-go/graphql, see that repository in detail.

Limitations

This plugin just aims to generate a simple gateway of gRPC.

Some of things could be solved and could not be solved. The most of limitations come from the IDL's power of expression -- some kind of GraphQL schema feature cannot implement by Protocol Buffers X(

Currently we don't support some Protobuf types:

  • Builtin oneof type
  • Wrapper types in google/protobuf/wrappers
  • Any types of google/potobuf/any

Contribute

  • Fork this repository
  • Customize / Fix problem
  • Send PR :-)
  • Or feel free to create issue for us. We'll look into it

Author

Yoshiaki Sugimoto

License

MIT

You can’t perform that action at this time.