Using the Endpoints Command Line Tool

You use the Endpoints command line tool to:

• Create the client library required for Java clients, such as Android clients.
• Create the discovery document required by iOS clients.

  Command line syntax

  The basic syntax is as follows:

  appengine-sdk/endpointscfg.py <command> <target_lang> <options> [class-name]
  

  where:

  • <command> is either get_client_lib or get_discovery_doc.
  • <target-lang> (used only in get_client_lib) to specify the type of client bundle you want to create. Currently, you are required to supply the value java.
  • <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
  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
  hostname	Specifies the discovery document rootURL. This option overrides the default value derived from the application entry inside the backend API project app.yaml (<application>.appspot.com). One use of this option is to supply the hostname localhost as the rootURL for local testing.	--hostname localhost
  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
  output	Sets the directory where the output will be written to. Default: the directory the tool is invoked from.	--output /mydir -o /mydir

  Generating a Discovery Doc

  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. Change directory to the directory containing your backend API's app.yaml file and API service classes. Alternatively, use the --application option to specify some other location of your application directory.

  2. Invoke the Endpoints command line tool as follows:

     appengine-sdk/endpointscfg.py get_discovery_doc your_module.YourServiceClass
     

     Using a more concrete example to generate the default REST discovery doc:

     appengine-sdk/endpointscfg.py get_discovery_doc helloworld_api.HelloWorldApi
     

     Generating an RPC discovery doc from an API implemented from multiple classes:

     appengine-sdk/endpointscfg.py get_discovery_doc --format rpc \
         helloworld_api.HelloWorldApi helloworld_api.GoodbyeApi
     

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

     API discovery document written to ./helloWorld-v1.discovery
     

     The discovery document is written to the current directory unless you specify some other output directory using the output option.

  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

  The Endpoints command line tool can be used to generate a Google Endpoints Java client library bundle. This bundle is the Java client library that can be used in your Java projects to call the backend API from which the bundle was generated. This bundle provides your Java client with all of the Google API client capabilities, including OAuth.

  What is supported in the bundle

  The following are supported in the 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.

  Library generation

  To generate the client library:

  1. Change directory to the directory containing your backend API's app.yaml file and API service classes. Alternatively, use the --application option to specify some other location of your application directory.

  2. Invoke the Endpoints command line tool as follows:

     appengine-sdk/endpointscfg.py get_client_lib java your_module.YourServiceClass
     

     Notice that java must be specified as shown above. Using a more concrete example to generate the client library:

     appengine-sdk/endpointscfg.py get_client_lib java helloworld_api.HelloWorldApi
     

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

     API client library written to ./helloWorld-v1.zip
     

  The discovery document is written to the current directory unless you specify some other output directory using the output option.

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.