Deploying and Testing an API

This page describes how to deploy your API.

Before you begin

Deploying an API

You can deploy your API using the App Engine Apache Maven or Gradle plugins. To deploy your API to production App Engine standard environment, use the command for your plugin:

  1. If this is the first time you are deploying the API, or if you have modified your API decorators, generate and deploy your API configuration file before deploying your API.

  2. Use the command for your plugin:


    mvn appengine:deploy


    gradle appengineDeploy

  3. Wait for the deployment to finish.

  4. Send a test request to your deployed API. For example, using cURL:

    curl \
        -H "Content-Type: application/json" \
        -X POST \
        -d '{"message": "echo"}' \

    Alternatively to cURL, use Google's API Explorer:

    1. In your browser, enter the URL, but replace YOUR-PROJECT-ID with your Cloud project ID.
    2. Click on your API, which is displayed in that page. For example, echo API.
    3. Click an API method, for example, echo.echo to select it.
    4. Fill in an expected value for the method. For the echo sample, fill in a value of 2.
    5. Click the request body to add a field.
    6. Select message as the field name and fill in a value; for example supply echo as the value.
    7. Click "Execute without OAuth". Your response will look like this:

        "message": "echo echo"

If you did not get a successful response, see Troubleshooting Response Errors.

Generating and deploying an API configuration

You must regenerate and re-deploy your API configuration when you deploy your API for the first time, and generally whenever you change configuration details in your @Api annotation.

To deploy the API configuration file:

  1. Generate an OpenAPI document using the framework tools, for example:


    mvn endpoints-framework:openApiDocs

    Generated file location: target/openapi-docs/openapi.json


    gradle endpointsOpenApiDocs

    Generated file location: build/endpointsOpenApiDocs/openapi.json

  2. Deploy the resulting configuration .json file, for example:


    gcloud endpoints services deploy target/openapi-docs/openapi.json


    gcloud endpoints services deploy build/endpointsOpenApiDocs/openapi.json

    The deploy command returns several lines of information, including a line similar to the following:

     Service Configuration with version "[2016-12-01R0]" uploaded for service ""
  3. Note the service configuration ID shown in the returned lines because you will need to use it later. For example, in the above lines, 2016-12-01R0 is the service configuration ID.

    You can always find the configuration ID later by invoking the command:

     gcloud endpoints configs list

    Replace YOUR-PROJECT-ID with your project ID.

  4. Edit your appengine-web.xml to add two environment variables:

        <env-var name="ENDPOINTS_SERVICE_NAME" value="" />
        <env-var name="ENDPOINTS_SERVICE_VERSION" value="YOUR_CONFIG_ID" />

    Replace YOUR-PROJECT-ID with your project ID, and the valueYOUR_CONFIG_ID with your service configuration ID.

  5. Redeploy your application.

Deploying to multiple app versions

For information on how to do API versioning, and how to deploy to versions, see Handling API Versioning

Running and testing API backends locally

To test your API locally:

  1. Build the project in the root directory of the project. For example, using Maven:


    mvn clean package


    gradle clean build
  2. Start the App Engine development server. For example, using Maven:


    mvn appengine:run


    gradle appengineRun
  3. Make an API request to test your API. For example, using curl:

    curl \
        -H "Content-Type: application/json" \
        -X POST \
        -d '{"message": "echo"}' \

Serving your API from a different path

To serve your API from a different path, in your web.xml file, change the url-pattern in the EndpointsServlet section and redeploy your API. For example:

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints Frameworks for App Engine
Need help? Visit our support page.