Notice: Over the next few months, we're reorganizing the App Engine documentation site to make it easier to find content and better align with the rest of Google Cloud products. The same content will be available, but the navigation will now match the rest of the Cloud products.

Java 17 is now generally available.

Structuring Web Services in App Engine

Region ID

The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

Learn more about region IDs.

Use the following document to understand how to structure the services and related resources of your app for App Engine.

Directory structure

Each version of your App Engine service is defined in an app.yaml configuration file. For simple apps, the minimum requirement for deployment is to define the app.yaml file. The app.yaml file acts as a deployment descriptor and defines the scaling type and the runtime, handlers, and other resource settings for a specific version of a service. If you are deploying several versions of a service, you can create multiple YAML files in the same directory to represent the configuration for each of your versions.

The file organization depends on which Java runtime you are using. You might need a WAR file or a JAR file, one for each service in your app. See the appropriate Java runtime developer guide for details.

Design considerations for instance uptime

Hardware or software failures that cause early termination or frequent instance restarts can occur without warning and can take considerable time to resolve. Your application should be able to handle such failures.

Here are some good strategies for avoiding downtime due to instance restarts:

  • Reduce the amount of time it takes for your instances restart or for new ones to start.
  • For long-running computations, periodically create checkpoints so that you can resume from that state.
  • Your app should be "stateless" so that nothing is stored on the instance.
  • Use queues for performing asynchronous task execution.
  • If you configure your instances to manual scaling:
    • Use load balancing across multiple instances.
    • Configure more instances than required to handle normal traffic.
    • Write fall-back logic that uses cached results when a manual scaling instance is unavailable.

Learn more about instances at How Instances are Managed.

The default service

Every App Engine application includes a default service. You must deploy the initial version of your app to the default service before you can create and deploy additional services to your app.

The default service can be optionally specified in the app.yaml with the setting service: default.

Requests sent to your app using your Cloud project are sent to the default service, for example, To learn more about targeting your other services, see Communicating Between Services.

Optional configuration files

The following configuration files control optional features that apply to all of the services in an individual app. See the following topics for details about each of the optional features:

  • dispatch.yaml overrides routing default rules by sending incoming requests to a specific service based on the path or hostname in the URL.
  • index.yaml specifies which indexes your app needs if using Datastore queries.
  • cron.yaml configures regularly scheduled tasks that operate at defined times or regular intervals.

Data and file storage considerations

From App Engine, you can easily access other Google Cloud services such as Datastore, Cloud SQL, and Cloud Storage.

You also have the option to use an external or third-party database if that database is supported by your language and accessible from your App Engine instance.

For details about storing files in Google Cloud or externally, see Understanding Data and File Storage.

You can also choose how you want to serve your static content. You can serve your app's static content directly from that app in App Engine, host your static content on a Google Cloud option like Cloud Storage, or use a third-party content delivery network (CDN). For more information about serving static content, see Serving Static Files.

What's next

If you are working with multiple services and want to deploy them together, see the steps to deploy multiple services.