Adding API Management

For your API to be managed by Cloud Endpoints, you must deploy an OpenAPI document that describes your API using version 2.0 of the OpenAPI Specification. This page describes how to generate and deploy an OpenAPI document that enables Cloud Endpoints to manage your API. For an overview of API Management, see Comparing Extensible Service Proxy and Endpoints Frameworks

If you do not add API management, your API will still serve requests, but your API will not appear in the Endpoints dashboard in the Cloud Console, and the functionality provided by Cloud Endpoints (such as authentication, logging, monitoring, and setting quotas) will not be available.

To add API management to your API:

  1. In your API project’s web.xml, add the API management servlet filter configuration:

    <!-- Add a filter that fetches the service config from service management. -->
    <filter>
        <filter-name>endpoints-api-configuration</filter-name>
        <filter-class>com.google.api.control.ServiceManagementConfigFilter</filter-class>
    </filter>
    
    <!-- Add a filter that performs Endpoints logging and monitoring. -->
    <filter>
        <filter-name>endpoints-api-controller</filter-name>
        <filter-class>com.google.api.control.extensions.appengine.GoogleAppEngineControlFilter</filter-class>
        <init-param>
            <param-name>endpoints.projectId</param-name>
            <param-value>${endpoints.project.id}</param-value>
        </init-param>
        <init-param>
            <param-name>endpoints.serviceName</param-name>
            <param-value>${endpoints.project.id}.appspot.com</param-value>
        </init-param>
    </filter>
    
    <filter-mapping>
        <filter-name>endpoints-api-configuration</filter-name>
        <servlet-name>EndpointsServlet</servlet-name>
    </filter-mapping>
    
    <filter-mapping>
        <filter-name>endpoints-api-controller</filter-name>
        <servlet-name>EndpointsServlet</servlet-name>
    </filter-mapping>

  2. Modify your API project build configuration:

    Maven

    1. Add the API management dependencies:

      <dependency>
          <groupId>com.google.endpoints</groupId>
          <artifactId>endpoints-management-control-appengine</artifactId>
          <version>1.0.6</version>
      </dependency>
      <dependency>
          <groupId>com.google.endpoints</groupId>
          <artifactId>endpoints-framework-auth</artifactId>
          <version>1.0.6</version>
      </dependency>
    2. Include the plugin that you can use to generate client libraries and an OpenAPI configuration file, openapi.json:

      <plugin>
          <groupId>com.google.cloud.tools</groupId>
          <artifactId>endpoints-framework-maven-plugin</artifactId>
          <version>1.0.2</version>
          <configuration>
              <!-- plugin configuration -->
              <hostname>${endpoints.project.id}.appspot.com</hostname>
          </configuration>
      </plugin>

    Gradle

    1. Add the API management dependencies:

      compile 'com.google.endpoints:endpoints-management-control-appengine:1.0.5'
      compile 'com.google.endpoints:endpoints-framework-auth:1.0.5'
    2. Declare the external dependency so that the plugin gets retrieved from Maven Central:

      classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
    3. Use the server-side Endpoints Framework Gradle plugin, which generates the OpenAPI configuration file:

      apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
    4. Configure the name of your Cloud Endpoints service:

      endpointsServer {
        // Endpoints Framework Plugin server-side configuration
        hostname = "${projectId}.appspot.com"
      }

  3. After modifying dependencies, clean your project and then build your API:

    Maven

        mvn clean
        mvn package

    Gradle

        gradle clean
        gradle build

  4. Generate the OpenAPI document, openapi.json:

    Maven

    mvn endpoints-framework:openApiDocs

    Gradle

    gradle endpointsOpenApiDocs

  5. Deploy the OpenAPI document:

     gcloud endpoints services deploy openapi.json
    

    This first time you deploy openapi.json, a new Cloud Endpoints service is created with the name YOUR_PROJECT_ID.appspot.com. On successful completion, you will see a line like the following that displays the service configuration ID and the service name:

    Service Configuration [2017-02-13r0] uploaded for service [example-project.appspot.com]
    

    In the example above, 2017-02-13r0 is the service configuration ID. The service configuration ID consists of a date stamp followed by a revision number. If you deploy openapi.json again, the revision number is incremented in the service configuration ID.

    If you need to display the service configuration ID again, run the following command, but replace [YOUR_PROJECT_ID] with the project ID of your Cloud project:

     gcloud endpoints configs list --service=[YOUR_PROJECT_ID].appspot.com
    

    You can create your own OpenAPI document and deploy it, rather than using a generated one. Simply replace openapi.json above with the path to your OpenAPI document. For more information on writing an OpenAPI document, see OpenAPI Overview.

  6. Edit your appengine-web.xml to set the value for an environment variable:

    <env-variables>
        <env-var name="ENDPOINTS_SERVICE_NAME" value="${endpoints.project.id}.appspot.com" />
    </env-variables>

    Replace ${endpoints.project.id} with your Cloud project ID. For example:

    <env-var name="ENDPOINTS_SERVICE_NAME" value="example-project.appspot.com" />
    
  7. Redeploy your application.

    Maven

    mvn appengine:deploy

    Gradle

    gradle appengineDeploy

  8. Test your API by making some requests to it.

  9. To view your API metrics, open the Cloud Endpoints dashboard for your project:
    Cloud Endpoints

After your API is managed by Cloud Endpoints, when you view logs on the Stackdriver Logging page in the GCP Console, the logs are available in the Produced API section grouped by service name.
View Logs

Send feedback about...

Cloud Endpoints Frameworks for App Engine