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:

   

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:

   

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:

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.