Each Endpoints API consists of a service class and its methods. To create an
Endpoints API, you define a subclass of remote.Service and
decorate it with @endpoints.api as follows:
@endpoints.api(name='yourApi',version='v1',
description='Tic Tac Toe API')
class TicTacToeApi(remote.Service):
...
To create a method for your API, decorate it with
@endpoints.method as follows:
@endpoints.method(YourRequestMessageClass,
YourResponseMessageClass,
name='foo.bar', ...)
def bar(self, request):
...
where YourRequestMessageClass and
YourResponseMessageClass are your own
Google Protocol RPC response
and request message classes. (See
Creating Message Classes for
Endpoints.)
We'll describe each of these decorators (@endpoints.api and
@endpoints.method ) in more detail below.
Defining the API (@endpoints.api)
You can supply several arguments to @endpoints.api to define
your API. The following table describes the available arguments:
| @endpoints.api Arguments | Description | Example |
|---|---|---|
name |
Required. The name of the API, which is used as the prefix for all
of the API's methods and paths. The name value:
|
'yourApi' |
version |
Required. Specifies your Endpoint’s version. | 'v1' |
description |
A short description of the API. This is exposed in the discovery service to describe your API, and may optionally also be used to generate documentation as described in Generating Client Libraries. | 'Sample API for a simple game' |
hostname |
Optional. The host name of your app engine application. | 'your_app_id.appspot.com' |
audiences |
Required if your API requires authentication and if you are supporting Android clients. A list of client IDs on behalf of which tokens are requested. For more information, see Allowed Client IDs and Audiences. | ['1-web-apps.apps.googleusercontent.com']
|
allowed_client_ids |
Required if your API uses authentication. List of client IDs for clients allowed to request tokens. For more information, see Allowed Client IDs and Audiences. | ['1-web-apps.apps.googleusercontent.com',
'2-android-apps.apps.googleusercontent.com',
endpoints.API_EXPLORER_CLIENT_ID] |
Allowed Client IDs and Audiences
If you want your Endpoints API to authenticate callers, you need to supply
a list of allowed_client_ids that are allowed to request tokens
that can be used with your application. This list should consist of the all
client IDs you have obtained through the Google API console for your web,
Android,
iOS,
and other clients. (This means that the clients must be known at API build-time.)
Note: If you want to test authenticated calls
to your API using the Google API Explorer, you must also supply its client ID,
which is available through the Endpoints library as
endpoints.API_EXPLORER_CLIENT_ID.
For Android clients, in addition to allowed_client_ids,
you must also configure audiences for your API. The
audiences argument is used only for Android clients. The
audiences argument specifies the list of client IDs on behalf of
which the token is requested.
Defining an API Method (@endpoints.method)
Note: The audiences,
scopes, and allowed_client_ids settings can be set
for the entire API via @endpoints.api, or for a method, via
@endpoints.method.
If these settings are specified at both the API and the method level, the method
setting overrides.
To create a method in your Endpoints API, decorate the corresponding Python
method with @endpoints.method, supplying arguments to configure the
use of the method. For example, you'll specify the
request and response message classes to
be used.
The available arguments are listed in the following table:
| @endpoints.method Arguments | Description | Example |
|---|---|---|
| Request Message Class | The Google Protocol RPC request message class to be used in the method call. Alternatively, you can supply the name of the class. | YourRequestClass |
| Response Message Class | The Google Protocol RPC response message class to be used in the method call. Alternatively, you can supply the name of the class. | YourResponseClass |
name |
An alternative name for this method. The name value:
|
'foo.bar' |
path |
The URI path to use to access this method. If you don't set this, the empty string is the path. | 'yourapi/path' |
http_method |
The HTTP method to use. If you don't set this, 'POST' is used
by default. |
'GET' |
audiences |
Overrides the equivalent argument specified in
@endpoints.api. For more information, see
Allowed Client IDs and
Audiences.
|
['1-web-apps.apps.googleusercontent.com']
|
allowed_client_ids |
This setting overrides the equivalent attribute specified in
@endpoints.api. For more information, see
Allowed Client IDs and
Audiences.
|
['1-web-apps.apps.googleusercontent.com',
'2-android-apps.apps.googleusercontent.com'] |
Creating Message Classes for Endpoints
Each API class method exposed in the endpoint requires a
protorpc request message
class and a response message class.
Complete information on these message classes is provided in the documentation for Google Protocol RPC and the Message class.