Skip to content

Configuration Reference

To define and bind HTTP endpoints to gRPC methods, you can use either configuration files or proto annotations directly within the proto files. For more details, refer to the Configuration documentation.

Gateway configuration files should include the following object (GatewayConfig) under the 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 a single gRPC method using the additional_bindings property. You must specify exactly one of the following fields to define the HTTP method: get, post, put, patch, delete, or custom.

To use an HTTP method not listed, utilize the custom property.

Warning

Any HTTP method can be used for the gRPC gateway. However, OpenAPI specification supports only a limited set of HTTP methods. Unsupported methods will not appear in the generated OpenAPI documents.

When using the custom field, the value must be a CustomPattern. For other fields, the value should be 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 HTTP method can be used and will function correctly in the gateway. However, methods not supported by OpenAPI will be excluded from the generated 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 field in the request proto message that is not bound to the HTTP body or path parameters will be automatically bound to query parameters.

You can explicitly bind one or more fields to query parameters by specifying the proto message selector and the desired query parameter name. Alternatively, you can use ignore to exclude specific fields from being bound to query parameters.

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. Defining aliases for long or nested fields can simplify query parameters. For example, using lower instead of options.lower_case.
  2. Setting ignore to true prevents the options.delay proto field from being bound 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. Defining aliases for long or nested fields can simplify query parameters. For example, using lower instead of options.lower_case.
  2. Setting ignore to true prevents the options.delay proto field from being bound 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 replaces the default auto-binding names. In the example above, using msg as an alias for the proto field message means only the query parameter msg will be bound to the proto field message. If you want to keep the original name as well, you can define multiple 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 an event streaming endpoint that continuously sends events to the client. Using chunked transfer for this is not ideal due to timeout constraints. However, using SSE (Server-Sent Events) or WebSockets is perfectly valid and recommended.

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
            }
        };
    }
}