How Requests are Handled

  1. Requests and domains
  2. Requests and servlets
  3. Request headers
  4. Responses
  5. The request timer
  6. SPDY
  7. Logging
  8. The environment
  9. Quotas and limits

Requests and domains

App Engine determines that an incoming request is intended for your application using the domain name of the request. A request whose domain name is is routed to the application whose ID is your_app_id. Every application gets an domain name for free. domains also support subdomains of the form, where subdomain can be any string allowed in one part of a domain name (not .). Requests sent to any subdomain in this way are routed to your application.

You can set up a custom top-level domain using the Google Cloud Platform Console custom domains page. You can assign subdomains of your business's domain to various applications, such as Google Mail or Sites. You can also associate an App Engine application with a subdomain. You can set up a custom domain after you create a new project. See Using Custom Domains and SSL for more information.

Requests for these URLs all go to the version of your application that you have selected as the default version in the Cloud Platform Console. Each version of your application also has its own URL, so you can deploy and test a new version before making it the default version. The version-specific URL uses the version identifier from your app's configuration file in addition to the domain name, in this pattern: You can also use subdomains with the version-specific URL:

The domain name used for the request is included in the request data passed to the application. If you want your app to respond differently depending on the domain name used to access it (such as to restrict access to certain domains, or redirect to an official domain), you can check the request data, such as the Host request header, for the domain from within the application code and respond accordingly.

If your app uses modules, you can address requests to a specific module and optionally a specific version of that module. For more information about module addressability, see Routing Requests to Modules.

Note: Google recommends using the HTTPS protocol to send requests to your app. Google does not issue SSL certificates for double-wildcard domains hosted at Therefore with HTTPS you must use the string "-dot-" instead of "." to separate subdomains, as shown in the examples below. You can use a simple "." with your own custom domain or with HTTP addresses.

Requests and servlets

When App Engine receives a web request for your application, it invokes the servlet that corresponds to the URL, as described in the application's deployment descriptor (the web.xml file in the WEB-INF/ directory). It uses the Java Servlet API, version 2.5, to provide the request data to the servlet and accept the response data .

App Engine runs multiple instances of your application, each instance has its own web server for handling requests. Any request can be routed to any instance, so consecutive requests from the same user are not necessarily sent to the same instance. The number of instances can be adjusted automatically as traffic changes.

By default, each web server processes only one request at a time. If you mark your application as thread-safe, App Engine can dispatch multiple requests to each web server in parallel. To do so, simply add a <threadsafe>true</threadsafe> element to appengine-web.xml.

The following example servlet class displays a simple message on the user's browser.

public class RequestsServlet extends HttpServlet {
  public void doGet(HttpServletRequest req, HttpServletResponse resp)
          throws IOException {
    resp.getWriter().println("Hello, world");

Request headers

An incoming HTTP request includes the HTTP headers sent by the client. For security purposes, some headers are sanitized or amended by intermediate proxies before they reach the application.

The following headers are removed from the request:

  • Accept-Encoding
  • Connection
  • Keep-Alive
  • Proxy-Authorization
  • TE
  • Trailer
  • Transfer-Encoding

In addition, the header Strict-Transport-Security is removed from requests served to any domains other than or *

These headers relate to the transfer of the HTTP data between the client and server, and are transparent to the application. For example, the server may automatically send a gzipped response, depending on the value of the Accept-Encoding request header. The application itself does not need to know which content encodings the client can accept.

App Engine specific headers

As a service to the app, App Engine adds the following headers to all requests:

Country from which the request originated, as an ISO 3166-1 alpha-2 country code. App Engine determines this code from the client's IP address. Note that the country information is not derived from the WHOIS database; it's possible that an IP address with country information in the WHOIS database will not have country information in the X-AppEngine-Country header. Your application should handle the special country code ZZ (unknown country).
Name of region from which the request originated. This value only makes sense in the context of the country in X-AppEngine-Country. For example, if the country is "US" and the region is "ca", that "ca" means "California", not Canada. The complete list of valid region values is found in the ISO-3166-2 standard.
Name of the city from which the request originated. For example, a request from the city of Mountain View might have the header value mountain view. There is no canonical list of valid values for this header.
Latitude and longitude of the city from which the request originated. This string might look like "37.386051,-122.083851" for a request from Mountain View.

App Engine services may add additional request headers:

The Task Queue service adds additional headers to requests from that provide details about the task in the request, and the queue it is associated with.

Requests from the Cron Service will also contain a HTTP header:

X-AppEngine-Cron: true

See Securing URLs for cron for more details.

Requests coming from other App Engine applications will include a header identifying the app making the request:


See the App Identity documentation for more details.


App Engine calls the servlet with a request object and a response object, then waits for the servlet to populate the response object and return. When the servlet returns, the data on the response object is sent to the user.

As explained below, there are limits that apply to the response you generate, and the response may be modified before it is returned to the client.