Get Requests and Caching

Connect supports performing idempotent, side-effect free requests using an HTTP GET-based protocol. This makes it easier to cache certain kinds of requests in the browser, on your CDN, or in proxies and other middleboxes.

info

This functionality is only supported when using the Connect protocol—using a Connect client with a Connect service. When using gRPC clients with Connect servers, or Connect clients with gRPC servers, all requests will use HTTP POST.

If you need HTTP GET support when talking to a vanilla gRPC server, you could use a proxy. Envoy supports translating between Connect clients and gRPC servers using the Connect-gRPC Bridge.

If you are using clients to make query-style requests, you may want the ability to use Connect HTTP GET request support. To opt-in for a given procedure, you must mark it as being side-effect free using the MethodOptions.IdempotencyLevel option:

service ElizaService {
  rpc Say(SayRequest) returns (SayResponse) {
    option idempotency_level = NO_SIDE_EFFECTS;
  }
}

Handlers will automatically support GET requests using this option, but ensure you have a recent enough version of Connect Go; v1.7.0 or newer is required. You will also need to re-run the code generation with v1.7.0 or newer.

It is still necessary to opt-in to HTTP GET on your client, as well. If you are using a Go client, you would specify the WithHTTPGet option when creating the Connect client.

client := elizav1connect.NewElizaServiceClient(
	http.DefaultClient,
	connect.WithHTTPGet(),
)

Methods annotated as side-effect free will use GET requests. All other requests will continue to use POST.

For other clients, see their respective documentation pages:

• Connect Node
• Connect Web
• Connect Kotlin

Caching

Using GET requests will not necessarily automatically make browsers or proxies cache your RPCs. To ensure that requests are allowed to be cached, a handler should also set the appropriate headers.

For example, you may wish to set the Cache-Control header with a max-age directive:

response := connect.NewResponse(&elizav1.SayResponse{})
response.Header().Set("Cache-Control", "max-age=604800")

This would instruct agents and proxies that the request may be cached for up to 7 days, after which it must be re-requested. There are other Cache-Control Response Directives that may be useful for your application as well; for example, the private directive would specify that the request should only be cached in private caches, such as the user agent itself, and not CDNs or reverse proxies—this would be appropriate, for example, for authenticated requests.

Distinguishing GET Requests

In some cases, you might want to introduce behavior that only occurs when handling HTTP GET requests. This can be accomplished using Request.HTTPMethod:

response := connect.NewResponse(&elizav1.SayResponse{})
if request.HTTPMethod() == http.MethodGet {
  response.Header().Set("Cache-Control", "max-age=604800")
}