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
- 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 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, useendpoints.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:
-
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.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 containingWEB-INF/appengine-web.xml
and 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.
- 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.
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:
-
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.Greetings
where
target/helloendpoints-1.0-SNAPSHOT
is the relative or absolute path to the target build directory containingWEB-INF/appengine-web.xml
and 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.
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 eitherget-client-lib
orget-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
|