An Endpoints API is a remote procedure call (RPC) service that provides remote methods accessible to external clients. Each Endpoints API consists of an RPC service class that subclasses the ProtoRPC remote.Service class, and one or more methods. When you define a method, you must also define message classes for the requests coming into that method and the responses returned by it. A message class performs a mapping function so the incoming data can be extracted and supplied to the service method properly, or supplied properly to the outgoing response.
If a request has path or querystring arguments, you'll use a ResourceContainer class for the mapping, instead of a simple message class.
Finally, you will need to decorate the API service class and class methods, and you will need to define message classes for the requests and responses, as described below:
Create the API
To create an Endpoints API:
Add the following required imports:
Define a subclass of
remote.Serviceand decorate it with
Notice that your API name and the name of your service class do not need to be the same.
Determine what data your method expects from the request and what data will be returned, and create a Message class for the request and response.
Note that if no arguments will appear in the request body, such as in a GET request, you could omit the message class for the request and simply use the value
If your request has path or querystring arguments, replace
YourRequestMessageClasswith an appropriate ResourceContainer.
For complete information on forming and using message classes, see the documentation for the Google Protocol RPC response and request message classes.
Create the desired method for your API, and decorate it with
If your request has path or querystring data, replace the request message type with an appropriate ResourceContainer.
Each of the decorators (
@endpoints.method) is described in more detail below.
Add the API server code, as described in Creating an API Server.
Defining the API (@endpoints.api)
You can supply several arguments to
@endpoints.api to define
your API. The following table describes the available arguments:
||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. If you specify
||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.||
||Specifies the frontend authentication requirement. Valid values are the following:
||Optional. Used to specify a different or more readable name for the API in the client library. This name is used to generate names in the client library; the backend API continues to use the value specified in the
||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.||
||Optional. The URL where users can find documentation about this version of the API. This will be surfaced in the API Explorer "Learn More" highlight at the top of the API Explorer page and also in the GPE plugin to allow users to learn about your service.||
||Optional. The host name of your app engine application.||
||Required. The name of the API, which is used as the prefix for all of the API's methods and paths. The
||Required. Specifies your Endpoint’s version.||
||Optional. The domain name of the entity that owns the API. Used together with
||Optional. The name of the entity that owns the API. Used together with
||Optional. Is used to further scope The "package" this API belongs to, with values separated by
||If not supplied, the default is the email scope (
||Optional. The text displayed in API Explorer as the title of your API, and exposed in the discovery and the directory services.||
Allowed Client IDs and Audiences
For OAuth2 authentication, an OAuth2 token is issued to a specific client ID,
which means that this client ID can be used for restricting access to your APIs.
When you register an iOS or Android applications in the Google Cloud Platform Console,
you create a client ID for it. This client ID is the one requesting an OAuth2
token from Google for authentication purposes. When the backend API is protected
by authm, an OAuth2 access token is sent and opened by Google Cloud Endpoints,
the client ID is extracted from the token, and then the ID is compared to the
backend's declared acceptable Client ID list (the
allowed_client_ids list should consist of the all
client IDs you have obtained through the Google Cloud Platform Console for your web,
and other client apps. (This means that the clients must be known at API build-time.)
If you specify an empty list, no clients can access the API.
If you use the
allowed_client_ids argument and you want to test authenticated
calls to your API using the Google API Explorer, you must supply its client ID
in the list of
allowed_client_ids: the value to use is
endpoints.API_EXPLORER_CLIENT_ID. Notice that if
endpoints.API_EXPLORER_CLIENT_ID, and you deploy your API, your
API will still be publically discoverable and can be publically accessed using
the API Explorer.
allowed_client_ids list protects the backend API from unauthorized clients. But
further protection is needed to protect the clients, so that their auth token
will work only for the intended backend API. For Android clients, this mechanism
audiences argument, in which you specify the client ID of the
Note that when you create a Google Cloud Platform Console Project, a default client ID is automatically created and named for use by the project. When you upload your backend API into App Engine, it uses that client ID. This is the web client ID mentioned in the backend API auth docs and the backend tutorial docs.
Defining an API Method (@endpoints.method)
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
@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:
|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.||
|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.||
||An alternative name for this method. The
||The URI path to use to access this method. If you don't set this, the empty string is the path.||
||The HTTP method to use. If you don't set this,
||Overrides the equivalent argument specified in
||This setting overrides the equivalent attribute specified in
ResourceContainer for path or querystring arguments
If the request contains path or querystring arguments, you cannot use a simple
Message class as described under Create the API. Instead,
you must use a
ResourceContainer class, as follows:
Define a message class that has all the arguments that will be passed in the request body. (If no arguments will appear in the request body, you don't need to define a message class: simply use
message_types.VoidMessage.) For example:
ResourceContainerwith the above message class as its first parameter, and subsequent parameters for the path and querystring arguments. For example:
where the first argument is the message class for the data in the request body and
timesis a number expected in the path or querystring accompanying the request.
ResourceContainerto the method handling the request, in the first parameter replacing the request message class that would otherwise be supplied in that location. This snippets show both the
pathparameter as shown, to include your API.
- If your
ResourceContainerhas a required argument, a client request must include it either in a querystring (for example,
yourApi?times=2), or the URL path (for example,
yourApi/2). However, in order for your API to receive an argument value via the URL path, you must also add the argument name to the API path as shown above for the
Creating an API Implemented with Multiple Classes
If you implement your API using more than one class, you use a slightly different decoration scheme. For example:
where you replace
api_collection with any name you want, so long as you use the same name for each class in the API. You must precede each class in the API with the decorator as shown in the snippet above.
About the resource name argument
The optional resource name argument for
api_class is the name of the class
that you want to exposed in the API; this is the name that will show up in the
API Explorer, prepended to any methods exposed in the class.
About the path argument
You don't have to explicitly specify a path argument, which indicates the
relative location at which the class methods will appear. Thus, in the snippet
above, no path is specified for the class
Shelves, so its methods will be accessible under
If you do specify a path, the path is appended to the root, but prepended to any paths provided within the class. It is the prefix that appears by default before any paths specified in the class.
In the snippet above, notice that the path
books is specified for class
Books. This means that any paths specified for its class methods will be
appended to the class, as shown below:
bookmark_func is accessible via the path
Serving a Multi-class API
In your endpoints.api_server
code that creates the API server, you supply the name you assigned for your
api_class collection. For example, where the collection name is
api_collection you would create the server as follows: