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:

    Maven

    mvn appengine:deploy

    Gradle

    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"}' \
        "https://YOUR-PROJECT-ID.appspot.com/_ah/api/echo/v1/echo?n=2"
    

    Alternatively to cURL, use Google's API Explorer:

    1. In your browser, enter the URL https://YOUR-PROJECT-ID.appspot.com/_ah/api/explorer, 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"
      }
      

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:

    Maven

    mvn endpoints-framework:openApiDocs

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

    Gradle

    gradle endpointsOpenApiDocs

    Generated file location: build/endpointsOpenApiDocs/openapi.json

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

    Maven

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

    Gradle

    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 "YOUR-PROJECT-ID.appspot.com"
    
  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 --service=YOUR-PROJECT-ID.appspot.com
    

    Replace YOUR-PROJECT-ID with your project ID.

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

    <env-variables>
        <env-var name="ENDPOINTS_SERVICE_NAME" value="YOUR-PROJECT-ID.appspot.com" />
        <env-var name="ENDPOINTS_SERVICE_VERSION" value="YOUR_CONFIG_ID" />
    </env-variables>
    

    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:

    Maven

    mvn clean package

    Gradle

    gradle clean build

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

    Maven

    mvn appengine:run

    Gradle

    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"}' \
        "${HOST}/_ah/api/echo/v1/echo?n=2"
    

Send feedback about...

Cloud Endpoints Frameworks for App Engine