Describe and create your own API

To serve your own API you need to describe it in Protobuf format, generate Go code and implement it first.

This example uses sample SummatorService API w/ YAML-annotated HTTP endpoints.

Describing your API

Describe your proto messages (doc) and gRPC service interface (doc+intro) using standard Protobuf+gRPC description: example

Describe HTTP bindings

Describe your HTTP handlers either by using google.api.http proto extension (example) or standalone YAML file. See this page for more info on pros and cons of each.

Install the generator

GO111MODULE=on go install github.com/utrack/clay/v2/cmd/protoc-gen-goclay

Generate Go code

Use a standard protoc generation command with goclay plugin enabled:

cd doc/example/pb
protoc -I/usr/local/include -I. \
  -I$GOPATH/src \
  -I$GOPATH/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis \
  --go_out=plugins=grpc:. --goclay_out=grpc_api_configuration=sum.yaml:. ./<YOUR_PROTOFILE>.proto

You can omit grpc_api_configuration option if you didn't use yaml to describe HTTP bindings.

Also, you can use prototool to generate the code.

Implement your handlers

Now for the fun part! Implement the generated interface using your own code: example

Wire up and serve the handlers

TODO: describe *ServiceDesc and clay server wireup