How Requests are Routed

HTTP requests from users can reach the appropriate services, versions, or instance in one of two ways:

  • A request with a URL that ends at the domain level can be routed according to App Engine's default address routing rules.
  • You can declare routes in a dispatch file that routes specific URL patterns according to your own rules.

If you test your app using the development server the available routing and dispatch features are slightly different. To programmatically create URLs that work with both production and development servers, use the ModulesService.getVersionHostname method. See routing in the development server to learn more.

Routing via URL

You can target an HTTP request with varying degrees of specificity. In the following examples can be replaced with your app's custom domain if you have one. The URL substrings "instance", "version", "service", and "app-id" represent application and service attributes that you have defined yourself.

These address forms are guaranteed to reach their target (if it exists). They will never be intercepted and rerouted by a pattern in the dispatch file:

If you are using backends or manually scaled front-ends you can send a request to a specific instance by specifying the instance. The instance is an integer in the range of [0, total_instances) and can be specified as follows:

Sends a request to the named service, version, and instance:
Sends a request to an available instance of the named service and version:

These address forms have a default routing behavior. Note that the default routing is overridden if there is a matching pattern in the dispatch file:

Sends a request to an available instance of the default version of the named service:
Sends a request to an available instance of the given version of the default service:
Sends the request to an available instance of the default version of the default service:

Default service

The default service is defined by explicitly giving a service the name "default," or by not including the name parameter in the service's config file. Requests that specify no service or an invalid service are routed to the default service. You can designate a default version for a service, when appropriate, in the Google Cloud Platform Console versions tab.

Soft routing

If a request matches the app-id.appspot portion of the hostname, but includes a service, version, or instance name that does not exist, then the request is routed to the default version of the default service. Soft routing does not apply to custom domains; requests to them will return a HTTP 404 status code if the hostname is invalid.

Restricting access to a service

All services are public by default. If you want to restrict access to a service, add the “login: admin” parameter to its handlers.

Routing with a dispatch file

For certain URLs (described above), you can create a dispatch file that overrides the routing rules. This file lets you send incoming requests to a specific service based on the path or hostname in the URL. For example, say that you want to route mobile requests like to a mobile frontend, route worker requests like to a static backend, and serve all static content from the default service.

Learn more about the format and syntax of the dispatch file.

Uploading the dispatch file

To upload the dispatch file, use the appcfg update_dispatch command, and specify the war directory for the default service. Be sure that all the services mentioned in the file have already been uploaded before using this command. # cd to the war directory containing the default service update_dispatch .

You can also upload the dispatch file at the same time you upload one or more services, by adding the optional auto_update_dispatch flag, which can be used in two forms: --auto_update_dispatch update <app-directory>|<files...> -D update <app-directory>|<files...>

Routing in the development server

Discovering instance addresses

The development server creates all instances at startup. Note that at this time basic scaling instances are not supported on the development server. Every instance that is created is assigned its own port. The port assignments appear in the server's log message stream. Web clients can communicate with a particular instance by targeting its port. Only one instance (and port) is created for automatic scaled services. It looks like this in the server log (note that services were previously called modules):

INFO: Module instance module2-auto is running at http://localhost:37251/

A unique port is assigned to each instance of a manual scaled service:

INFO: Module instance manualmodule instance 0 is running at http://localhost:43190/
INFO: Module instance manualmodule instance 1 is running at http://localhost:52642/

In addition, each manual scaled service is assigned one extra port so clients can access the service without specifying a specific instance. Requests to this port are automatically routed to one of the configured instances:

INFO: Module instance manualmodule is running at http://localhost:12361/

The following table shows how these services can be called in the development server and in the App Engine environment:

Service Instance Development server address App Engine address
service2-auto (not used) http://localhost:37251/
manualservice 0 http://localhost:43190/
manualservice 1 http://localhost:52642/
manualservice (not used) http://localhost:12361/

Dispatch files

All dispatch files are ignored when running the development server. The only way to target instances is through their ports.