Skip to main content

Get Requests and Caching

Beta software

connect-python is in beta. 1.0 will include a new Protobuf implementation built from scratch by Buf, which may introduce breaking changes. Join us on Slack if you have questions or feedback.

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.

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

Services will automatically support GET requests using this option.

It is still necessary to opt-in to HTTP GET on your client, as well. Generated clients include a use_get parameter for methods that are marked with NO_SIDE_EFFECTS.

response = await client.say(SayRequest(sentence="Hello"), use_get=True)

For other clients, see their respective documentation pages:

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:

ctx.response_headers()["cache-control"] = "max-age=604800"
return SayResponse()

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 with RequestContext.http_method:

if ctx.http_method() == "GET":
    ctx.response_headers()["cache-control"] = "max-age=604800"
return SayResponse()