gRPC-Gateway

The casing package provides utility functions for converting string formats, specifically for handling CamelCase and JSON-compatible casing. It includes two primary functions:

• Camel: Converts strings to CamelCase (originally from github.com/golang/protobuf/protoc-gen-go/generator).
• JSONCamelCase: Converts strings to a JSON-compatible CamelCase format (originally from github.com/protocolbuffers/protobuf-go/internal/strs).

Note: These functions are licensed by The Go Authors.

If you are looking for alternatives to grpc-gateway for gRPC-to-REST transcoding, consider the following projects based on your runtime and configuration needs:

Node.js Alternatives

• grpc-dynamic-gateway: A dynamically configured alternative written in Node.
• rest2grpc: A statically configured alternative written in Node.

Proxy and Cloud Alternatives

• Envoy proxy gRPC-JSON transcoder: An Envoy proxy filter that translates incoming JSON requests to gRPC and back.
• Google Cloud Platform HTTP/JSON gRPC transcoding: A GCP product that provides similar transcoding functionality.

Other Language Implementations

• grpc-starter transcoding: A Java implementation based on Spring Boot.
• grpc-rest-api-example: A Java Maven multi-module project example showcasing gRPC-Gateway usage.

grpc-gateway is a reverse-proxy that provides an HTTP+JSON interface to your existing gRPC services.

While gRPC is efficient and supports many languages, you might need a RESTful API to:

• Maintain backwards-compatibility with existing systems.
• Support clients or languages that do not have robust gRPC support.
• Leverage the existing ecosystem of RESTful tooling and aesthetics.

To use it, you add a small amount of configuration to your gRPC service definitions (using protocol buffers) to attach HTTP semantics, which then allows you to generate the proxy.

The gRPC-Gateway is a plugin for the Google protocol buffers compiler (protoc). It reads protobuf service definitions and generates a reverse-proxy server that translates RESTful HTTP/JSON API calls into gRPC.

This allows you to provide APIs in both gRPC and HTTP/JSON formats simultaneously by using google.api.http annotations within your service definitions. This eliminates the need to write a separate HTTP/JSON service manually.

gRPC-Gateway performs several automatic mappings between HTTP and gRPC:

• Headers:
  • Authorization header $\rightarrow$ authorization gRPC request header.
  • HTTP request source IP $\rightarrow$ X-Forwarded-For gRPC request header.
  • HTTP request host $\rightarrow$ X-Forwarded-Host gRPC request header.
  • Other IANA Permanent HTTP header keys $\rightarrow$ prefixed with grpcgateway-.
  • Headers starting with Grpc-Metadata- $\rightarrow$ mapped to gRPC metadata (prefixed with grpcgateway-).
• Marshaling: Default marshaling uses protojson (configurable).
• Path Templates: Supports google.api.http syntax (e.g., /api/v1/{name=projects/*/topics/*}).
• Errors: gRPC error codes are mapped to specific HTTP status codes.

When generating stubs for grpc-gateway, you can choose between two primary tools:

1. protoc: The industry-standard, classic generation tool. It is widely used but has a steeper learning curve.
2. buf: A modern tool designed for better user experience and speed. It provides additional features like linting and breaking change detection that protoc does not natively offer.

When using constrained path templates in google.api.http, the generator expands them into the OpenAPI URL verbatim. This ensures that the literal prefix remains in the URL and each wildcard becomes its own OpenAPI parameter. This is necessary because the proto field binds to the full matched substring.

If a single proto field expands into multiple wildcards, subsequent parameters are suffixed with _1, _2, etc. All synthetic parameters point back to the same underlying proto field, which the grpc-gateway runtime reconstructs from the full matched substring at request time.

While both facilitate JSON/HTTP-to-gRPC communication, they differ in implementation and usage:

• gRPC-Gateway: A code generator that produces a Go implementation of a reverse proxy based on annotations in your .proto files. It requires a generation step.
• grpc-httpjson-transcoding: A library that uses protobuf descriptors as configuration and does not require a code generation step. It is often used as a component within existing proxies, such as Google Cloud Endpoints or the Envoy gRPC-JSON transcoder filter.

Key Behavior Difference: By default, gRPC-Gateway does not escape path parameters in the same way as the transcoding library, though this behavior can be configured.

The grpc-gateway supports the google.api.field_behavior option to mark field characteristics in the OpenAPI output:

• REQUIRED: Marks a field as required.
• OUTPUT_ONLY: Marks a field as readonly.

Note: OPTIONAL, IMMUTABLE, and INPUT_ONLY are currently defined in Google's API but are not yet implemented in the OpenAPI output.

import "google/api/field_behavior.proto";

message MyMessage {
    string a_required_field = 1 [(google.api.field_behavior) = REQUIRED];
}

The resulting merged document follows these ordering rules:

• Top-level fields follow the OpenAPI 3.1.0 declaration order.
• paths and webhooks are emitted in the order they appeared in the input files.
• components/* sub-maps are sorted by key.
• tags appear in the order they were first encountered.