Testing an API backend follows the typical App Engine pattern of using the
development server to run the web app locally during development and incremental
testing, followed by deployment to production when you are ready for real-world
testing.

Running and testing API backends locally

To test the backend, you'll use the API Explorer, which is a tool that lets you
test APIs interactively without using a client app. This tool is
automatically run for you when you navigate to your backend API's subdirectory
/_ah/api/explorer as we'll describe in the instructions below.

To test the API backend locally on the development server:

If necessary, specify a different port and address other than the defaults.
For example, if you want the app to listen to the local network, you may need to
change the address to 0.0.0.0. For instructions, see
Specifying a port for local testing.

Start the API backend by invoking the development app server. Using Maven,
invoke the command from the project's <app>-ear subdirectory (not from the
<app>-war):

mvn appengine:devserver

Wait til the backend loads; if it loads successfully, this message is displayed:

INFO: Dev App Server is now running.

In your browser, visit the URL

http://localhost:8080/_ah/api/explorer

Double-click the API you created to display the list of its methods.

Click the method you wish to test, fill in any request fields as needed, then
click Execute to test the method: the request will be displayed along with
the response.

If you want to use curl instead of the API Explorer, you can alternatively
test the API backend by sending an test request using
curl. The following request makes a call to
a sample Board API backend to send a request to our sample tictactoe game:

Testing clients against the backend

You can test your client against a backend API running in production App Engine
at any time without making any changes. However, if you want to test your client
against a backend API running on the local development server, you'll need to make
changes as described below:

The first time you deploy to production App Engine, you may be prompted to
supply login information; supply it as directed.

If the deployment fails with the error 403 Forbidden You do not have permission to modify this app (app_id=u'your-app-id'),
check your source file your-app/src/main/webapp/WEB-INF/appengine-web.xml and
make sure the value for the <application> element is set to a valid
application ID.

After you deploy, you can use the API Explorer to experiment with your API without using a client
app by visiting

https://your_app_id.appspot.com/_ah/api/explorer

Important: It may take several moments for the API to load. If the API
loading message does not go away, and your API does not appear, clear your
cookies and refresh the API Explorer. If problems persist, follow the procedures
provided under Troubleshooting a deployment failure.

Alternatively, use the discovery service to view your API by visiting

https://your_app_id.appspot.com/_ah/api/discovery/v1/apis

Checking for a Successful Deployment

After you upload the API, you will see a success message if the
files upload correctly. However, after the files are uploaded, App Engine does
more work unpacking the API and deploying it. If there is a failure during this
process, you are not informed about it. You must check the logs to determine
success.

There is a some type of exception being thrown by your app that is preventing your app from starting.

Check your app's logs to narrow down the exception being thrown. Check for errors logged from the /_ah/spi/BackendService.getApiConfigs handler, which the Google Cloud Endpoints server uses to retrieve your API configuration. Here is what such a log might look like:

Endpoints configuration not updated. There are authentication requirements on the /_ah/spi handler that are preventing the Google Cloud Endpoints server from accessing the app.

Remove the authentication requirements on that handler from your app's web.xml file (see Security and Authentication for the lines to remove). Note: this error is not caused by setting the file to require HTTPS, as described in Secure URLs, because this does work with Endpoints.

Deploying to multiple app versions

When you deploy your backend API, you deploy it to the
Cloud project ID you created for your API. This ID is the same one used by App Engine for your
backend API. When you deploy, in addition to the App Engine/Cloud Project ID,
you must also specify the App Engine version you deploy to.
You specify the App Engine/Cloud Project ID in the <application> field in the
/WEB-INF/appengine-web.xmlfile; you specify the application version in the
<version> field. Notice that the App Engine app version is not the same thing
as the backend API version number, which you specify in the version attribute
of the @Api annotation.

As shown in the figure above, you can deploy multiple API versions to the same
App Engine App version. And, you can have many App Engine App versions.

Accessing backend API versions deployed to an application default version

The first App Engine version you deploy your backend API to is the default
version. That remains the default version until you explicitly change it using
the Google Developers Console; select your project in the console, then
navigate to Compute > App Engine > Versions.

The UI allows you to specify which version is the default.
The default is the version running at the URL http://your_app_id.appspot.com.
All of the backend API versions deployed to that App Engine app version can be accessed using that URL.

If you need to access API versions that are not deployed to the default
App Engine app version, you use a version-specific URL.

To access backend API versions that are deployed to non-default App Engine
versions of your app, you must include the version specifier in the URL, like
this: https://version-dot-your_app_id.appspot.com. For example, suppose your
default app version is 1, but you want to access a backend API version
deployed to App Engine app version 2; you would use this URL:
https://2-dot-your_app_id.appspot.com.

Important: For backend APIs, only host names formed as shown above using -dot-
in place of literal periods will work for versioned apps.

Accessing backend API versions deployed to non-default modules

If you need to access API versions that are not deployed to the default
App Engine module, you would use a version-specific URL using the dot syntax
as follows:

`https://<module-name>-dot-<app-name>.appspot.com/_ah/spi/...`

Managing your backend API versions

In managing your API versions, consider these recommendations:

When you want to introduce an incremental, but non-breaking change, keep the
API version constant and deploy over the existing API.

When you introduce a breaking change to your API, increment the API version.

For additional protection, increment the App Engine app version as well and
then deploy the new API version to that new App Engine app version. This lets
you use the built-in flexibility of App Engine to quickly switch between App
Engine versions and serve from the old working versions if you run into
unexpected problems.

The following table is an illustration of cascading backend API versions to
different App Engine app versions:

App Version

backend API version

1

v1 --> v1 (2) --> v1 (n)

2

v1 (n)

v2 --> v2 (2) --> v2 (n)

3

v1 (n)

v2 (n)

v3 --> v3 (2) --> v3 (n)

As shown in the table, incremental, non-breaking updates to v1 of the API are rolled
out, each overwriting the previous version. When breaking changes are introduced, the
API version is incremented to v2 and it is deployed to a new App Engine app version.
That allows you to switch back to the previous app version if needed.

In the table, notice that app version 2 supports both the latest v1 version
and the new v2 version of your API. If you don't delete the existing v1 code
from your project, deploying the project will result in both v2 and vl (n)
of your API being deployed to App version 2.