Generating Libraries and Discovery Docs with the Endpoints Tool
Generating a client library bundle from a backend API
Generating a discovery doc from a backend API
Command line syntax for the Endpoints tool
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.)
Note: You can alternatively use Maven to generate Maven client library bundles and discovery documents from the backend API, as described in Generating Client Libraries. However, this option won't generate a Gradle client bundle to use with an Android project.
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
Warning: The generated discovery document should not be edited.
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:
Note: The instructions below are for a Maven project. If you use Eclipse, the project layout will be slightly different and you will have to invoke the Endpoints commmand line tool from the parent directory of the war directory in your target build output.
If you haven't already done so, build the backend API.
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.Greetingswhere
target/helloendpoints-1.0-SNAPSHOTis the relative or absolute path to the target build directory containingWEB-INF/appengine-web.xmland the compiled backend classes:
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; it 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.shcommand for Linux and Mac OSX. If you use Windows, useendpoints.cmdinstead. 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:
If you haven't already done so, build the backend API.
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.Greetingswhere we are building a Gradle bundle and where
target/helloendpoints-1.0-SNAPSHOTis the relative or absolute path to the the target build directory containingWEB-INF/appengine-web.xmland the compiled backend classes: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.
The bundle also contains a
readme.htmlfile 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:
where:
<command>is eitherget-client-liborget-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.
Note: If your API is implemented from multiple classes, specify each of them separated by a space.
Options
You can use the following options:
Option Name | Description | Example |
|---|---|---|
| Lets you specify which type of client bundle should be produced. Specify |
|
| Lets you specify the service class or classes from a path other than the default |
|
| For |
|
| Sets the path to the build target directory |
|
| Sets the directory where the output will be written to. |
|