Skip to content

Configuration Reference

To define and bind HTTP endpoints to gRPC methods, you can use either configuration files or proto annotations directly in the proto files. See Configuration to learn more.

Gateway configuration files accept the following object (GatewayConfig) under gateway key:

Field Name
 Type Description
endpoints [EndpointBinding] List of all gRPC-HTTP bindings.

Example

gateway:
    endpoints:
        - selector: "~.MyService.MyMethod"
          get: "/route"

EndpointBinding

EndpointBinding represents an HTTP endpoint(s) to gRPC method binding.

Field Name
 Type Description
selector string selector is a dot-separated gRPC service method selector.

If the selector begins with ~., the current proto package will be added to the beginning
of the path. For instance: ~.MyService. Since no proto package can be deduced in the global
config file, this alias cannot be used in the global config file.

If the selector does not begin with ~., it will be treated as a fully qualified method name (FQMN).

NOTE: In proto annotations, this field gets automatically assigned, thus it is only applicable in configuration files.
get string (RoutePattern) get defines route for a GET HTTP endpoint.
put string (RoutePattern) put defines route for a PUT HTTP endpoint.
post string (RoutePattern) post defines route for a POST HTTP endpoint.
delete string (RoutePattern) delete defines route for a DELETE HTTP endpoint.
patch string (RoutePattern) patch defines route for a PATCH HTTP endpoint.
custom CustomPattern custom can be used for custom HTTP methods.

Not all HTTP methods are supported in OpenAPI specification and will not be included in the
generated OpenAPI document.
body string body is a request message field selector that will be read via HTTP body.

* indicates that the entire request message gets decoded from the body.
An empty string (default value) indicates that no part of the request gets decoded from the body.

NOTE: Not all methods support HTTP body.
response_body string response_body is a response message field selector that will be written to HTTP response.

* or an empty string indicates that the entire response message gets encoded.
query_params [ QueryParameterBinding ] query_params are explicit query parameter bindings that can be used to rename
or ignore query parameters.
additional_bindings [ AdditionalEndpointBinding ] additional_bindings holds additional bindings for the same gRPC service method.
disable_query_param_discovery bool disable_query_param_discovery can be used to avoid auto binding query parameters.

Default: false
stream StreamConfig stream holds configurations for streaming methods.

HTTP Method & Route

Each EndpointBinding object can define multiple HTTP bindings to one gRPC method via additional_bindings property. HTTP method needs to be defined by specifying precisely one and only one of the get, post, put, patch, delete or custom fields.

If you would like to use an HTTP method that is not listed, you can use the custom property to use any HTTP method.

Warning

You can use any HTTP method for the gRPC gateway. However, since OpenAPI specification only supports a limited set of HTTP methods, the unsupported methods do NOT get listed in the generated OpenAPI documents.

If the custom field is used, the value must be a CustomPattern. For other fields, the value is a RoutePattern.

Example

sound_gateway.yaml
1
2
3
4
gateway:
  endpoints:
    - post: "/echo"
      selector: "~.SoundService.Echo"
sound.proto
1
2
3
4
5
6
7
service SoundService {
    rpc Echo(EchoRequest) returns (EchoResponse) {
        option (meshapi.gateway.http) = {
            post: "/echo"
        };
    }
}

RoutePattern

This is a string pattern that can contain parameters bound to the proto request fields. Message field selectors enclosed in curly braces get bound to the request message payload.

For instance: /path/{path.to.field}

Example

Consider the following request message: 

1
2
3
4
5
6
7
8
message NestedMessage {
    string field = 1;
}

message Request {
    NestedMessage nested = 1;
    string name = 2;
}

/path/{name} would bind to field name of the Request message.

Nested fields are supported so /path/{name}/{nested.field} is valid.

Wildcard

If you want a field to contain all segments, including slashes, you can use the {<selector>=*} pattern.

Example

1
2
3
message Request {
    string file_path = 1;
}

Route pattern /path/{file_path=*} would match /path/a/b/c/d/e.jpg and capture file_path as /a/b/c/d/e.jpg.

AdditionalEndpointBinding

This object is similar to EndpointBinding excluding the additional_bindings key.

Example

sound_gateway.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
gateway:
  endpoints:
    - get: "/echo"
      selector: "~.SoundService.Echo"
      additional_endpoints:
        - get: "/another-route"
        - post: "/echo-with-post"
          body: "*"
        - custom:
            path: "/echo"
            method: "LOG"
sound.proto
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
service SoundService {
    rpc Echo(EchoRequest) returns (EchoResponse) {
        option (meshapi.gateway.http) = {
            get: "/echo",
            additional_endpoints: [
              {get: "/another-route"},
              {post: "/echo-with-post", body: "*"},
              {
                custom: {method: "LOG", path: "/echo"}
              }
            ]
        };
    }
}

CustomPattern

CustomPattern describes an HTTP pattern and custom method.

Field Name
 Type Description
method string method is the custom HTTP method.
path string path is the HTTP path pattern.

Example

sound_gateway.yaml
1
2
3
4
5
6
gateway:
  endpoints:
    - custom:
        method: "TRACE"
        path: "/echo"
      selector: "~.SoundService.Echo"
sound.proto
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
service SoundService {
    rpc Echo(EchoRequest) returns (EchoResponse) {
        option (meshapi.gateway.http) = {
            custom: {
                method: "TRACE",
                path: "/echo"
            }
        };
    }
}

Warning

Any method can be used and will work in the gateway. However, methods not recognized by OpenAPI will be skipped when generating the documentation.

QueryParameterBinding

QueryParameterBinding describes a query parameter to request message binding.

Field Name
 Type Description
selector string selector is a dot-separated path to the request message's field.
name string name is the name of the HTTP query parameter that will be used.
ignore bool ignore avoids reading this query parameter altogether (default: false).

By default, any fields in the request proto message not bound to the HTTP body or path parameters are bound to query parameters.

You can bind one or more fields to query parameters by specifying the proto message selector and the query parameter name or use ignore to avoid binding them at all.

Example

Consider the following request message: 

1
2
3
4
5
6
7
8
9
message EchoOptions {
    int32 delay = 1;
    bool lower_case = 2;
}

message EchoRequest {
    EchoOptions options = 1;
    string message = 2;
}

sound_gateway.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
gateway:
  endpoints:
    - post: "/echo"
      selector: "~.SoundService.Echo"
      query_parameters:
        - selector: "message"
          name: "msg"
        - selector: "options.lower_case" # (1)!
          name: "lower"
        - selector: "options.delay"
          ignore: true # (2)!
  1. It can be helpful to define aliases for long or nested fields, in this case lower instead of options.lower_case.
  2. Setting ignore to true ignores binding options.delay proto field to any query parameter.
sound.proto
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
service SoundService {
    rpc Echo(EchoRequest) returns (EchoResponse) {
        option (meshapi.gateway.http) = {
            post: "/echo",
            query_parameters: [
                {selector: "message", name: "msg"},
                {selector: "options.lower_case", name: "lower"}, // (1)!
                {selector: "options.delay", ignore: true} // (2)!
            ]
        };
    }
}
  1. It can be helpful to define aliases for long or nested fields, in this case lower instead of options.lower_case.
  2. Setting ignore to true ignores binding options.delay proto field to any query parameter.

In this example, in the HTTP request, you can use msg and lower query parameters directly:

/echo?msg=something&lower=true

Info

Defining aliases overrides the default auto-binding names. In the example above, when using msg as an alias for the proto field message, only the query parameter msg will be bound to the proto field message. To retain the original name, you can define additional aliases for the same selector.

StreamConfig

StreamConfig sets the behavior of the HTTP server for gRPC streaming methods.

Field Name
 Type Description
disable_websockets bool disable_websockets indicates whether or not websockets are allowed for this method.
The client must still ask for a connection upgrade.
disable_sse bool disable_sse indicates whether or not server-sent events are allowed.

see: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events

SSE is only used when Accept-Type from the request includes MIME type text/event-stream.
disable_chunked_transfer bool disable_chunked indicates whether or not chunked transfer encoding is allowed.

NOTE: Chunked transfer encoding is disabled in HTTP/2 so this option will only be available if the request
is HTTP/1.

Example

Imagine there is an events streaming endpoint that keeps sending events to the client. For this, using chunked transfer is not ideal because of the time out constraints. Using SSE or WebSockets however is perfectly valid.

notification_gateway.yaml
1
2
3
4
5
6
gateway:
  endpoints:
    - post: "/notify"
      selector: "~.NotificationService.Notify"
      stream:
        disable_chunked_transfer: true
notification.proto
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
service NotificationService {
    rpc Notify(NotifyRequest) returns (stream NotifyResponse) {
        option (meshapi.gateway.http) = {
            get: "/events",
            stream: {
                disable_chunked_transfer: true
            }
        };
    }
}