Hide
Python

Generating Libraries and Discovery Docs with the Endpoints Tool

  1. Generating a client library bundle from a backend API
  2. Generating a discovery doc from a backend API
  3. Command line syntax for the Endpoints tool
  4. Options

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 used to generate the bundle. This bundle 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:

Option Name Description Example
application By default, the tool generates from the backend API in the current directory.
If you want to generate using a different directory, specify the path to the directory containing the app.yaml and service classes that implement your API.
--application /my_path/my_api_dir
build-system Lets you specify which type of client bundle should be produced. Specify gradle for a Gradle client bundle for Android, maven for a Maven client bundle, or default (or simply omit this option) for a bundle that contains only the dependency libraries and source jar. --build-system=gradle
-bs gradle
hostname Specifies the discovery document rootURL.
This option overrides the default value derived from the application entry inside the backend API project app.yaml (<application>.appspot.com).
One use of this option is to supply the hostname localhost as the rootURL for local testing.
--hostname localhost
format For get_discovery_doc only. Sets the format of the generated discovery document.
Possible values: rest or rpc.
Default is rest.
--format rpc
-f rpc
output Sets the directory where the output will be written to.
Default: the directory the tool is invoked from.
--output /mydir
-o /mydir