Proto

Protos hold the protobuf definitions the gRPC transcoding plugin reads.

In the console ProtosEngine resource proto

What a proto is

A proto holds a protobuf definition, the services and messages a gRPC backend speaks, under Content. grpc-transcode on a route reads it to turn an HTTP request into a call of one of those services. The content is protobuf source text, or a compiled descriptor set encoded in base64.

The plugin names a proto by the ID it was given when it was saved, shown on its page, and not by its Name. It names a service by its full name, the package and then the service, for example orders.Orders.

When to use it

• The orders service speaks gRPC only, and the web shop and the partners should call it with JSON over HTTP.
• A mobile app that carries no gRPC library asks for an order with GetOrder, through a route that transcodes its request.
• A definition that imports other files, compiled with its imports into one descriptor set and stored in base64.
• Several routes that transcode to the same gRPC service, each naming one proto instead of carrying a copy of its own.

Not for turning an HTTP request into a gRPC call — see grpc-transcode (Translates HTTP and JSON requests into gRPC calls and back).

Set it up

Describe the orders service so that REST calls can be transcoded to it

A route transcodes to it with the grpc-transcode plugin. The plugin's proto_id is the ID the engine gives this Proto when it is saved, shown on its page, and not its name. The plugin names the service as orders.Orders and the method, over an upstream whose scheme is grpc or grpcs.

Under General set Name to orders, set Description to The gRPC contract of the orders service and fill Labels as in the JSON below. Under Definition set Content to syntax = "proto3"; package orders; message GetOrderRequest { string id = 1; } message Order { string id = 1; string status = 2; int64 total_cents = 3; } service Orders { rpc GetOrder(GetOrderRequest) returns (Order) {} } .

proto · as the console saves it

{
  "name": "orders",
  "desc": "The gRPC contract of the orders service",
  "labels": {
    "team": "orders"
  },
  "content": "syntax = \"proto3\";\npackage orders;\n\nmessage GetOrderRequest {\n  string id = 1;\n}\n\nmessage Order {\n  string id = 1;\n  string status = 2;\n  int64 total_cents = 3;\n}\n\nservice Orders {\n  rpc GetOrder(GetOrderRequest) returns (Order) {}\n}\n"
}

Things to know

• Content — With the package orders and the service Orders, a route whose grpc-transcode names orders.Orders and GetOrder sends its requests to the backend as calls of that service. A backend that does not serve it answers, and the client gets 501 with unknown service orders.Orders.
• Content — Compiled alone when you save: an import is refused, even of a Google well-known type, while a base64 descriptor set that carries its imported files is accepted.
• Content — A file that declares a service without a package line is refused when you save.
• Content — Text that is not protobuf, hello world for example, is refused when you save.
• Content — A proto without content is refused when you save.
• Labels — A label value with a space, two words for example, is refused when you save.
• AdviceGive a proto the name of its package, orders for the package orders, so that the list of protos shows which ID a route should name.
• The engine assigns the id when the object is created; it is not the name, and it is what other objects refer to.

Settings

The fields as the console shows them, section by section.

General

Namenamestring

1 to 256 characters

Descriptiondescstring

up to 256 characters

Labelslabelsobject

A value is one word of up to 256 characters, with no spaces. An object whose keys are any name, each with a string as its value.

Definition

Routes that transcode JSON to gRPC read their services and messages from here.

ContentcontentstringRequired

Protobuf source text, or a compiled descriptor set encoded in base64. A file that declares a service needs a package line, or the engine fails the save.

1 to 1048576 characters