Hide
Java

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

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. If you haven't already done so, build the backend API.

  2. Invoke the Endpoints command line tool as follows:

    appengine-java-sdk-x.x.x/bin/endpoints.sh get-discovery-doc --war=target/helloendpoints-1.0-SNAPSHOT \ com.google.appengine.samples.helloendpoints.Greetings
    

    where target/helloendpoints-1.0-SNAPSHOT is the relative or absolute path to the target build directory containing WEB-INF/appengine-web.xml and the compiled backend classes:

    Where to invoke endpoints.sh

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

    INFO: Successfully processed /usr/local/directory/helloendpoints/target/helloendpoints-1.0-SNAPSHOT/WEB-INF/appengine-web.xml
    API Discovery Document written to ./helloworld-v1-rest.discovery
    

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

Before starting, note two things about the instructions provided below:

  • The instructions use the endpoints.sh command for Linux and Mac OSX. If you use Windows, use endpoints.cmd instead. The options and invocations are the same for both versions of this tool.
  • The instructions are for a Maven project. If you use Eclipse, the project layout will be slightly different.

To generate a client library bundle:

  1. If you haven't already done so, build the backend API.

  2. Invoke the Endpoints command line tool similarly to the following:

    appengine-java-sdk-x.x.x/bin/endpoints.sh get-client-lib --war=target/helloendpoints-1.0-SNAPSHOT \
    -bs gradle com.google.appengine.samples.helloendpoints.Greetings
    

    where we are building a Gradle bundle and where target/helloendpoints-1.0-SNAPSHOT is the relative or absolute path to the the target build directory containing WEB-INF/appengine-web.xml and the compiled backend classes:

    Where to invoke endpoints.sh

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

    INFO: Successfully processed /usr/local/directory/helloendpoints/target/helloendpoints-1.0-SNAPSHOT/WEB-INF/appengine-web.xml
    API client library written to ./helloworld-v1-java.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

Before you use the Endpoints command line tool, you need to build your backend project because the tool requires compiled binaries. You can optionally supply the --war= option pointing to the build target output directory containing the WEB-INF/appengine-web.xml file and compiled java classes if you don't want to use the default (--war="./war").

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:

Option Name Description Example
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
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 in your build target directory, 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.
Supply the value java for Java clients, such as Android.
war Sets the path to the build target directory WEB-INF that contains appengine-web.xml and other metadata.
Default: ./war.
--war=target/helloendpoints-1.0-SNAPSHOT
-w target/helloendpoints-1.0-SNAPSHOT
output Sets the directory where the output will be written to.
Default: the directory the tool is invoked from.
--output=/mydir
-o /mydir