Using the Endpoints Command Line Tool

You use the Endpoints command line tool to:

• Generate a client library from a backend API, so that Java clients can access the backend API. For example, Android clients
• Generate the discovery document from the backend API. The discovery doc is required by iOS clients.

Command line syntax

The basic syntax is as follows:

appengine-java-sdk-x.x.x/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:

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 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-java-sdk-x.x.x/bin/endpoints.sh get-discovery-doc packagename.YourApiClass
   

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

   appengine-java-sdk-x.x.x/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-java-sdk-x.x.x/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 from a backend API

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:

• 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.

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-java-sdk-x.x.x/bin/endpoints.sh get-client-lib packagename.YourApiClass
   

   Using a more concrete example to generate the client library:

   appengine-java-sdk-x.x.x/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-java-sdk-x.x.x/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-java-sdk-x.x.x/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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.