Testing and Deploying an API Backend
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.
After you finish creating your Endpoints API and generating client libraries , you can test and deploy the API backend.
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:
-
Start the API backend by invoking the development app server:
google_appengine/dev_appserver.py --port=8080 your-app-directory-path # Replace the port number with another one if you wish. # Also specify --address=0.0.0.0 if you want devserver to listen to the local network.
-
Test the API backend in the API Explorer by navigating to
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 a test request using
curl
. The following
request makes a call to a sample Board API backend that is
part of a Tic Tac Toe game:
curl --header "Content-Type: application/json" \
-X POST -d '{"state": "----X----"}' \
http://localhost:8888/_ah/spi/tictactoe/v1/board
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:
- For more information on testing JavaScript clients locally, see Testing a JavaScript client against a local development server .
- For more information on testing Android clients locally, see Testing an Android client against a local development server .
Deploying an API backend
When you are satisfied that your API backend works as expected, you can deploy it to App Engine. Deploying an API backend is no different from deploying a regular App Engine app: full instructions for deploying are provided in the deploying and uploading topic.
To deploy:
-
Invoke the upload script as follows:
your-sdk-install-dir-path/appcfg.py update your-app-dir
-
Use the API Explorer to experiment with your API by visiting
https://your_app_id.appspot.com/_ah/api/explorer
-
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.
To check the logs after you deploy your API,
- Visit the Google Developers Console .
- Click on your API project.
- Click on App Engine in the sidebar to the left.
- Click on Logs in the sidebar to the left.
-
Look at the logs nearest in time to the time you deployed. A successful API deployment results in a log that looks something like this:
013-09-30 18:39:09.781 Endpoints: https://2-dot-test-pont.appspot.com/_ah/api/helloWorld@v2 Saved
or
2013-09-30 16:07:17.987 Endpoints: https://7-dot-test2.appspot.com/_ah/api/guestbook@v1 OK
An unsuccessful deployment has this kind of log:
https://7-dot-test2.appspot.com/_ah/api/Guestbook@v2 ERROR
If the logs indicate a deployment failure, try re-uploading your API.
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
app.yaml
file; 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
argument
to the
@endpoints.api
decorator.
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, then navigate to Compute > App Engine > Versions .
The UI allows you to specify which version is the default.
The defaul 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.
Accessing backend API versions deployed to non-default application versions
What if you want to access API versions that are not deployed to the default App Engine app version? In that case, you would 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
.
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 |
|