Google App Engine

Using the Endpoints Command Line Tool

The easiest way to generate client libraries and discovery documents is to use Maven, as described in Generating Client Libraries. However, if this option is not available or desirable, you can alternatively use the Endpoints command line tool.

You use the Endpoints command line tool to:

  • Create the client library required for Java clients, such as Android,
  • Create the discovery document required by iOS clients.

Command line syntax

The basic syntax is as follows:

appengine-sdk/bin/endpoints.sh <command> <options> [class-name]

where:

  • <command> is either get-client-lib or get-discovery-doc.
  • <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
classpath Lets you specify the service class or classes from a path other than the default <war-directory>/WEB-INF/libs and war-directory>/WEB-INF/classes, where war-directory is the directory specified in the war option, or simply war if that option is not supplied. --classpath=/usr/lib com.google.devrel.samples.ttt.spi.BoardV1
-cp /usr/lib com.google.devrel.samples.ttt.spi.BoardV1
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
language For get-client-lib only. Sets the target output programming language. If not set, the default is java.
Only java is supported.
--language=java
-l java
war Sets the path to the war directory where web-appengine.xml and other metadata are located.
Default: ./war.
--war=/mydir/war
-w /mydir/war
output Sets the directory where the output will be written to.
Default: the directory the tool is invoked from.
--output=/mydir
-o /mydir

Generating a Discovery Doc

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 parent directory of your project's /war directory. Alternatively, use the --war option to specify the location of war.

  2. Invoke the Endpoints command line tool as follows:

    appengine-sdk/bin/endpoints.sh get-discovery-doc packagename.YourApiClass
    

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

    appengine-sdk/bin/endpoints.sh get-discovery-doc com.google.devrel.samples.ttt.spi.BoardV1
    

    Generating an RPC discovery doc from an API implemented from multiple classes, separating each class by a space:

    appengine-sdk/bin/endpoints.sh get-discovery-doc --format=rpc \
        com.google.devrel.samples.ttt.spi.BoardV1 com.google.devrel.samples.ttt.spi.ScoresV1
    
  3. When successful, the tool displays a message similar to:

    INFO: Successfully processed ./war/WEB-INF/appengine-web.xml
    API Discovery Document written to ./tictactoe-v1-rest.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

The Endpoints command line tool can be used to generate a Google Endpoints Java client library bundle. This bundle is the Java client library that can be used in your Java projects to call the backend API from which the bundle was generated. This bundle provides your Java client with all of the Google API client capabilities, including OAuth.

What is supported in the bundle

The following are supported in the client bundle:

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.

Library generation

To generate the client library:

  1. Change directory to parent directory of your project's /war directory. (Alternatively, use the --war option to specify the location of war.

  2. Invoke the Endpoints command line tool as follows:

    appengine-sdk/bin/endpoints.sh get-client-lib packagename.YourApiClass
    

    Using a more concrete example to generate the client library:

    appengine-sdk/bin/endpoints.sh get-client-lib com.google.devrel.samples.ttt.spi.BoardV1
    

    An example that generates the client library from an API implemented from multiple service classes:

    appengine-sdk/bin/endpoints.sh get-client-lib \
        com.google.devrel.samples.ttt.spi.BoardV1 com.google.devrel.samples.ttt.spi.ScoresV1
    

    An example that uses a classpath to specify the service classes:

    appengine-sdk/bin/endpoints.sh get-client-lib \
        --classpath=/usr/lib com.google.devrel.samples.ttt.spi.BoardV1 \
        com.google.devrel.samples.ttt.spi.ScoresV1
    
  3. When successful, the tool displays a message similar to:

    INFO: Successfully processed ./war/WEB-INF/appengine-web.xml
    API client library written to ./tictactoe-v1-java.zip
    

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

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.