Creating an Endpoints API
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:
import endpoints from protorpc import messages from protorpc import message_types from protorpc import remote
-
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): ...
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.
class YourResponseMessageClass(messages.Message): message = messages.StringField(1) class YourRequestMessageClass(messages.Message): message = messages.StringField(1)
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
message_types.VoidMessage
.If your request has path or querystring arguments, replace
YourRequestMessageClass
with 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
@endpoints.method
as follows:@endpoints.method(YourRequestMessageClass, YourResponseMessageClass, name='foo.bar', ...) def bar(self, request): ...
If your request has path or querystring data, replace
YourRequestMessageClass
with an appropriate ResourceContainer .Each of the decorators (
@endpoints.api
and@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:
@endpoints.api Arguments | Description | Example |
---|---|---|
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]
|
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']
|
auth_level
|
Specifies the frontend authentication requirement. Valid values are the following:
|
@api(..., auth_level=AUTH_LEVEL_REQUIRED)
|
canonical_name
|
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
name
property.
|