Generating Libraries and Discovery Docs with the Endpoints Tool

We recommend that you use the latest version of this feature, which is renamed to Cloud Endpoints Frameworks for App Engine. This new version supports App Engine standard environment, provides lower latency, and has better integration with App Engine. For more details, see Migrating to 2.0.

You can use the Endpoints command line tool to generate client library bundles and discovery docs. Android clients need a client library bundle to access the backend API. iOS clients need the discovery doc.

These instructions assume you have created your backend API. (See the backend API tutorial for more information on creating backend APIs.)

The Endpoints command line tool is provided in the SDK: google_appengine/endpointscfg.py.

Generating a discovery doc from a backend API

A Google discovery document describes the surface for a particular version of an API. The information provided by the discovery document includes API-level properties such as an API description, resource schemas, authentication scopes, and methods. The Endpoints command line tool can generate a discovery document in either REST format (the default) or RPC format (required for generating an iOS client).

To generate the discovery document:

1. Change directory to the directory containing your backend API's app.yaml file and API service classes. Alternatively, use the --application option to specify some other location of your application directory.

2. Invoke the Endpoints command line tool as follows:

   google_appengine/endpointscfg.py get_discovery_doc your_module.YourServiceClass
   

   Using a more concrete example to generate the default REST discovery doc:

   google_appengine/endpointscfg.py get_discovery_doc helloworld_api.HelloWorldApi
   

   Generating an RPC discovery doc from an API implemented from multiple classes:

   google_appengine/endpointscfg.py get_discovery_doc --format rpc \
       helloworld_api.HelloWorldApi helloworld_api.GoodbyeApi
   

3. When successful, the tool displays a message similar to:

   API discovery document written to ./helloWorld-v1.discovery
   

   The discovery document is written to the current directory unless you specify some other output directory using the output option.

If you are getting the discovery doc for use with an iOS client, see Using Endpoints in an iOS Client for information on using the discovery document.

Generating a client library bundle from a backend API

The Endpoints command line tool can be used to generate a Maven client bundle, a Gradle client bundle, or a bundle that contains only the dependency libraries and source jar. This bundle is the Java library be used in your client to call the backend API; it provides your client with all of the Google API client capabilities, including OAuth.

If you are using the client library with an Android app, we recommend that you use a Gradle client bundle.

How to generate the client library bundle

1. Change directory to the directory containing your backend API's app.yaml file and API service classes. Alternatively, use the --application option to specify some other location of your application directory.

2. Invoke the Endpoints command line tool as follows:

   google_appengine/endpointscfg.py get_client_lib java -bs desired_client_bundle your_module.YourServiceClass
   

   Using a more concrete example to generate the client library:

   google_appengine/endpointscfg.py get_client_lib java -bs gradle helloworld_api.HelloWorldApi
   

3. When successful, the tool displays a message similar to:

   API client library written to ./helloWorld-v1.zip
   

The client library bundle is written to the current directory unless you specify some other output directory using the output option.

What is supported in the client library bundle?

The following are supported in the Java client bundle:

• Java 5 and higher: standard (SE) and enterprise (EE).
• Android 1.5 and higher.
• Google App Engine.
• The bundle also contains a readme.html file that provides details on using the client library, which dependent jars are needed for each application type (web, installed, or Android application), and so forth.

Command line syntax for the Endpoints tool

The basic syntax is as follows:

google_appengine/endpointscfg.py <command> <target_lang> <options> [class-name]

where:

• <command> is either get_client_lib or get_discovery_doc.
• <target-lang> (used only in get_client_lib) to specify the type of client bundle you want to create. Currently, you are required to supply the value java (for Java clients such as Android)
• <options>, if supplied, is one or more items shown in the Options table
• [class name] is the full class name of your API.

Options

You can use the following options: