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:

1. Add the following required imports:

   import endpoints
   from protorpc import messages
   from protorpc import message_types
   from protorpc import remote
   

2. 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.

3. 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.

4. 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.

5. 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:

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 Cloud Console for your web, Android, iOS, 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.

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)

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:

Using 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:

1. 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:

   class MyRequest(messages.Message):
     my_string = messages.StringField(1)
     my_number = messages.IntegerField(2, required=True)
   

2. Define a ResourceContainer with the above message class as its first parameter, and subsequent parameters for the path and querystring arguments. For example:

   YOUR_RESOURCE_CONTAINER = endpoints.ResourceContainer(
           MyRequest,
           times=messages.IntegerField(2, variant=messages.Variant.INT32,
                                   required=True))
   

   where MyRequest is the message class for the data in the request body and times is a number expected in the path or querystring accompanying the request.

3. Supply the ResourceContainer to the method handling the request, in the first parameter replacing the request message class that would otherwise be supplied in that location:

   @endpoints.method(YOUR_RESOURCE_CONTAINER, YourResponseMessageClass,
                    path='yourApi/{times}', http_method='GET',
                    name='greetings.getGreeting')
   def greeting_get(self, request):
   

4. Add the path parameter as shown, to include your API.

5. If your ResourceContainer has 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 {times} argument in path='yourApi/{times}.

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:

    an_api = endpoints.api(name='library', version='v1.0')

    @an_api.api_class(resource_name='shelves')
    class Shelves(remote.Service):
    ...

    @an_api.api_class(resource_name='books', path='books')
    class Books(remote.Service):
    ...

where you replace an_api 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 /_ah/api/library/v1.

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:

    @an_api.class(resource_name='books', path='books')
    class Books(remote.Service):
            @endpoints.method(Req, Resp, path='bookmark')
            def bookmark_func(self, request):

where bookmark_func is accessible via the path /_ah/api/library/v1/books/bookmark

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:

    an_api = endpoints.api(name='library', version='v1.0')

you would create the server as follows:

    endpoints.api_server([an_api])

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.