Required Files and Configuration

This page describes the files that must be included in your backend API in order to use Cloud Endpoints.

  1. The backend API class file
  2. appengine-web.xml
  3. web.xml

If you use Android Studio and Cloud Tools for Android Studio to build your app and backend API, Android Studio automatically generates the neccessary web.xml and appengine-web.xml files.

Or if you use Maven and the artifacts described in the Android Backend Tutorial setup and configuration pages, your project automatically has the web.xml and appengine-web.xml generated with the proper entries.

Your project must contain, at a minimum, the following files:

File and Location Description
/src/main/java/<packagepath>/<your_api_class>.java The class file (or files, if you implement your API across multiple classes) containing your backend API.
/src/main/webapp/WEB-INF/appengine-web.xml The web app deployment descriptor required for App Engine configuration.
/src/main/webapp/WEB-INF/web.xml The standard Java web app deployment descriptor mapping URLs to servlets and other information.

The contents of each of these required files is documented in the following sections.

The backend API class file

The required and optional contents of the class file (or files, if you use a multi-class API) are fully described in the topic Endpoint Annotations.

appengine-web.xml

The bare minimum contents required for this file are as follows:

<?xml version="1.0" encoding="utf-8"?>
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <application>your-app-id</application>
    <version>1</version>
    <threadsafe>true</threadsafe>

    <system-properties>
        <property name="java.util.logging.config.file" value="WEB-INF/logging.properties"/>
    </system-properties>
</appengine-web-app>

where:

  • your-app-id is replaced with the actual App Engine application ID for your backend API.
  • version_number is replaced by the App Engine version number you want to use, with the first version of your app starting at version 1. (For a full discussion of App Engine versions, see Deploying to multiple app versions.)
  • threadsafe is set to true if you want App Engine to send multiple requests in parallel, or set to false, if you want App Engine to send requests serially.

Additional but optional settings are available. See the appengine-web.xml reference for more information.

web.xml

Sample bare minimum contents required for this file are shown as follows:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"  version="2.5">
    <servlet>
        <servlet-name>SystemServiceServlet</servlet-name>
        <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
        <init-param>
            <param-name>services</param-name>
            <param-value>com.example.helloworld.YourFirstAPI</param-value>
        </init-param>
    </servlet>
    <servlet-mapping>
        <servlet-name>SystemServiceServlet</servlet-name>
        <url-pattern>/_ah/spi/*</url-pattern>
    </servlet-mapping>
    <welcome-file-list>
        <welcome-file>index.html</welcome-file>
    </welcome-file-list>
</web-app>

where you replace:

  • <param-value>com.google.devrel.samples.helloendpoints.Greetings</param-value> with your own API class name. Note that if your API is a multi-class API, each class is listed inside this same <param-value> each separated by a comma, for example:

    <param-value>com.google.devrel.samples.helloendpoints.Greetings,com.google.devrel.samples.helloendpoints.AndGoodbyes</param-value>

  • The value for <welcome-file> with the page used as the landing page of the web app, if there is one. You can omit the entire <welcome-file-list> block if you don't supply a web client (JavaScript client) for your backend API.

Additional but optional settings are available. For more information, see The Deployment Descriptor: web.xml. However, note that the information under Security and Authentication and Secure URLs do not apply to backend APIs.