You can generate client library bundles that allow applications to access your API using the Endpoints Frameworks command-line tool. When you generate a client library, the Endpoints Frameworks command-line tool automatically generates a Discovery document that describes the surface of your API.
The Endpoints Frameworks command-line tool,endpointscfg.py
is
available in the Endpoints Frameworks library. For information on
installing the Endpoints Frameworks library using pip
, see
Installing the Endpoints Frameworks library.
Note that the following commands assume you have installed the
Endpoints Frameworks library in a directory called lib
. Additionally,
the instructions assume you have created your backend API. See the
Endpoints Frameworks for Python tutorial
for an example of using the Endpoints Frameworks command-line tool on
sample code.
Generating a client library bundle from an API
You can use the Endpoints Frameworks command-line tool to generate the following types of client bundles:
Maven: This bundle includes a
pom.xml
file with the Endpoints Frameworks and Google API Client Library dependencies. Thereadme.html
file provides detailed information on what you need to add to yourpom.xml
file for different types of client applications and how to build a client library for your API using Maven.Gradle: This bundle includes a
build.gradle
file with the Endpoints Frameworks and Google API Client Library dependencies. Thereadme.html
file provides detailed information on what you need to add to yourbuild.gradle
file for different types of client applications and how to build a client library for your API using Gradle.Default client bundle: This bundle contains all the dependency libraries and the generated
source.jar
file, which is the Java library that you use in your client to call your API. This bundle provides your client with all of the Google API Client Library capabilities, including OAuth. Thereadme.html
file lists the.jar
files that are required for different types of client applications and other details for using the client library.
If you are using the client library with an Android app, we recommend that you use a Gradle client bundle.
Generating the client library
To generate the client library:
Change directory to the directory containing your API's
app.yaml
file and API service classes. Alternatively, use the--application
option to specify some other location of your application directory.Invoke the Endpoints Frameworks command-line tool similar to the following:
lib/endpoints/endpointscfg.py get_client_lib java -bs gradle main.EchoApi
where
main
is the class containing your API andEchoApi
is your API name.Wait for the tool to generate the client library; on success the tool displays a message similar to this one:
API client library written to ./echo-v1.zip
Add the client library JAR to your Android app.
Repeat the preceding steps every time you modify your API code.
The client library bundle is written to the current directory unless you
specify some other output directory using the
output
option.
Command-line syntax
The basic syntax is as follows:
/path-to/your-app/lib/endpointscfg.py get_client_lib TARGET_LANG OPTIONS CLASS_NAME
where:
TARGET_LANG
specifies the type of client bundle you want to create. Currently, you are required to supply the valuejava
(for Java clients such as Android).OPTIONS
, if supplied, is one or more items shown in the Options tableCLASS_NAME
is the fully qualified class name of your API.
Options
You can use the following options:
Option name | Description | Example |
---|---|---|
application |
By default, the tool generates from the backend API in the current directory.If you want to generate using a different directory, specify the path to the directory containing the app.yaml and service classes that implement your API. |
--application /my_path/my_api_dir |
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 |
hostname |
Specifies the discovery document rootURL .This option overrides the default value derived from the application entry inside the backend API project app.yaml ([YOUR_APP_ID].appspot.com ) and the hostname defined in the decorator for your API.One use of this option is to supply the hostname localhost as the rootURL for local testing. |
--hostname localhost |
format |
Don't specify this because the only supported value is the default value, rest for REST. |
Not needed, use default. |
output |
Sets the directory where the output is written to.Default: the directory the tool is invoked from. | --output /mydir -o /mydir |
Supported client platforms
The following platforms are supported in the client bundle produced by the Endpoints Frameworks command-line tool:
- Java 7 and higher:
- Android 1.6 and higher.
- App Engine.
Generating an OpenAPI document from an API
The endpointscfg.py
tool provides a command to generate an OpenAPI document
from an API backend. The command syntax is:
lib/endpoints/endpointscfg.py get_openapi_spec
[-h]
[-a APPLICATION]
[--hostname HOSTNAME]
[-o OUTPUT]
service [service ...]
positional arguments:
service Fully qualified service class name.
optional arguments:
-h, --help Show this help message and exit.
-a APPLICATION, --application APPLICATION
The path to the Python App Engine application.
--hostname HOSTNAME Default application hostname, if none is specified for the API service.
-o OUTPUT, --output OUTPUT
The directory to store output files.
--x-google-api-name Add the 'x-google-api-name' field to the generated OpenAPI document.
For example, using the echo
example:
$ lib/endpoints/endpointscfg.py get_openapi_spec --hostname=echo-example.appspot.com main.EchoApi
OpenAPI spec written to ./echov1openapi.json