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 get_hostname 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 appspot.com 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:

https://instance-dot-version-dot-service-dot-app-id.appspot.com
http://instance.version.service.my-custom-domain.com

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

https://version-dot-service-dot-app-id.appspot.com
http://version.service.my-custom-domain.com

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:

https://service-dot-app-id.appspot.com
http://service.my-custom-domain.com

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

https://version-dot-app-id.appspot.com
http://version.my-custom-domain.com

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

https://app-id.appspot.com
http://my-custom-domain.com

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 http://simple-sample.appspot.com/mobile/ to a mobile frontend, route worker requests like http://simple-sample.appspot.com/work/ 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 by itself, use the appcfg update_dispatch command, specify the directory that contains the dispatch file, and use the -A option to specify your project ID. Be sure that all the services mentioned in the file have already been uploaded before using this command.

# cd to the project directory or the default service directory that contains dispatch.yaml
appcfg.py -A <PROJECT_ID> update_dispatch .

Note that the dispatch file is uploaded automatically when you update a service in this case:

• You use the command appcfg.py -A <PROJECT_ID> update <dir> pointing at a service's directory
• There is a service configuration file named app.yaml in the directory
• The dispatch file is also in the directory

Routing in the development server

Discovering instance addresses

The development server creates all manual scaling instances at startup. Instances for automatic and basic scaling services are managed dynamically. The server assigns a port to each service, and clients can depend on the server to load-balance and select an instance automatically. The port assignments for addressing each service appear in the server's log message stream. Here are the ports for an app that defines three services (the scaling type of each service is not relevant):

INFO Starting module "default" running at: http://localhost:8084
INFO Starting module "module1" running at: http://localhost:8082
INFO Starting module "module2" running at: http://localhost:8083

When you use a service's address (for example http://localhost:8082/), the server will select (or create) an instance of the service and send the request to that instance.

The server assigns unique ports to each instance of a service. To discover these ports you need to use the admin server. There is a unique port for the admin server, which appears in the message log:

INFO Starting admin server at: http://localhost:8000

This address takes you to the admin server console. From there you can click on Instances to see the dynamic state of your app's instances:

A separate entry will appear for each manual and basic instance. The instance numbers are links with unique port addresses for each instance. You can hover over a link to see the port assigned to that instance, or click on the link to send a request directly to that instance.

Dispatch files

If your app includes a dispatch.yaml file, the log messages stream will include a dispatcher port:

INFO Starting dispatcher running at: http://localhost:8080

Requests to this port are routed according to the rules in the dispatch file. The server does not support dispatch.yaml file rules that include hostnames (for example, url: "customer1.myapp.com/*"). Rules with relative path patterns (url: "*/fun") will work, so you can use URLs like http://localhost/fun/mobile to reach instances. The server will report an error in the log stream if you try to start an application with a dispatch.yaml file that contains host-based rules.