Decorators

The Cloud Endpoints Frameworks for Python decorators describe API configuration, methods, parameters, and other vital details that define the properties and behavior of the Endpoint.

This page describes the available decorators in detail. For information about using the decorators to create your API, see the following:

• Creating the API
• Creating an API implemented with multiple classes

Defining the API ( @endpoints.api )

You can supply several arguments to @endpoints.api to define your API. The following table describes the available arguments:

limit_definitions

To define quotas for your API, you specify the optional limit_definitions argument to @endpoints.api . To configure a quota, you must also:

• Install version 2.4.5 or later of the Endpoints Frameworks library.
• Add the metric_costs argument to the method decorator for each method that you want to apply a quota to.

See Configuring quotas for all the steps required to set up a quota.

You specify a list of one or more LimitDefinition instances, similar to the following:

  quota_limits 
 = 
 [ 
 endpoints 
 . 
 LimitDefinition 
 ( 
 "name" 
 , 
 "Display name" 
 , 
 limit 
 ) 
 ] 
 

Each LimitDefinition instance must have the following values:

Example

 quota_limits 
 = 
 [ 
 endpoints 
 . 
 LimitDefinition 
 ( 
 'read-requests' 
 , 
 'Read Requests' 
 , 
 1000 
 ), 
 endpoints 
 . 
 LimitDefinition 
 ( 
 'list-requests' 
 , 
 'List Requests' 
 , 
 100 
 ), 
 endpoints 
 . 
 LimitDefinition 
 ( 
 'write-requests' 
 , 
 'Write Requests' 
 , 
 50 
 ) 
 ] 
 @endpoints 
 . 
 api 
 ( 
 name 
 = 
 'bookstore' 
 , 
 version 
 = 
 'v1' 
 , 
 limit_definitions 
 = 
 quota_limits 
 ) 

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 Android applications in the Google Cloud 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 auth, an OAuth2 access token is sent and opened by Endpoints Frameworks for App Engine, 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).

The allowed_client_ids list should consist of all the client IDs you have obtained through the Google Cloud console for your web, Android , 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.

Note that in each API method where you want to check for proper authentication, you must call endpoints.get_current_user() . See Authenticating users for more information.

If you use the allowed_client_ids argument and you want to test authenticated calls to your API by using the API Explorer, you must supply its client ID in the list of allowed_client_ids by specifying the constant endpoints.API_EXPLORER_CLIENT_ID . Notice that if allowed_client_ids contains only endpoints.API_EXPLORER_CLIENT_ID , and you deploy your API, your API is still publicly discoverable and publicly accessible in the API Explorer.

About audiences

The allowed_client_ids list protects the backend API from unauthorized clients. But further protection is needed to protect the clients , so that their authentication token works only for the intended backend API. For Android clients, this mechanism is the audiences argument, in which you specify the client ID of the backend API.

Note that when you create a Google Cloud 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 API auth .

Third-party authentication token issuer

If your application accepts authentication tokens that aren't Google ID tokens and are issued by third-party issuers, you need to properly set audiences and issuers arguments in @endpoints.api to provide the information about the third-party issuers. For example:

  @endpoints 
 . 
 api 
 ( 
 audiences 
 = 
 { 
 'auth0' 
 : 
 [ 
 'aud-1.auth0.com' 
 , 
 'aud-2.auth0.com' 
 ]}, 
 issuers 
 = 
 { 
 'auth0' 
 : 
 endpoints 
 . 
 Issuer 
 ( 
 'https://test.auth0.com' 
 , 
 'https://test.auth0.com/.well-known/jwks.json' 
 )}) 
 class 
  
 GreetingApi 
 ( 
 remote 
 . 
 Service 
 ): 
 

Defining an API method ( @endpoints.method )

You can set the audiences , scopes , and allowed_client_ids settings for the entire API by using @endpoints.api , or for a method, by using @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 API, decorate the corresponding Python method with @endpoints.method , supplying arguments to configure the use of the method. For example, you specify which request and response Message classes to use.

The available arguments are listed in the following table:

Using ResourceContainer for path or query string arguments

If the request contains path or query string arguments, you cannot use a simple Message class as described in Create the API . Instead, you must use a ResourceContainer class, as follows:

1. Define a Message class that has all the arguments that are passed in the request body. If there aren't any arguments in the request body, you don't need to define a Message class: simply use message_types.VoidMessage .) For example:

     class 
     
    Greeting 
    ( 
    messages 
    . 
    Message 
    ): 
     
    """Greeting that stores a message.""" 
    message 
    = 
    messages 
    . 
    StringField 
    ( 
    1 
    ) 
    
   

2. Define a ResourceContainer with the Message class that you defined in the previous step as the first parameter. Specify the path and query string arguments in the subsequent parameters. For example:

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

   where the first argument is the Message class for the data in the request body and times is a number expected in the path or query string 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. This snippet shows both the ResourceContainer and the endpoints.method :

     # This ResourceContainer is similar to the one used for get_greeting, but 
    # this one also contains a request body in the form of a Greeting message. 
    MULTIPLY_RESOURCE 
    = 
    endpoints 
    . 
    ResourceContainer 
    ( 
    Greeting 
    , 
    times 
    = 
    messages 
    . 
    IntegerField 
    ( 
    2 
    , 
    variant 
    = 
    messages 
    . 
    Variant 
    . 
    INT32 
    , 
    required 
    = 
    True 
    ), 
    ) 
    @endpoints 
    . 
    method 
    ( 
    # This method accepts a request body containing a Greeting message 
    # and a URL parameter specifying how many times to multiply the 
    # message. 
    MULTIPLY_RESOURCE 
    , 
    # This method returns a Greeting message. 
    Greeting 
    , 
    path 
    = 
    "greetings/multiply/ 
    {times} 
    " 
    , 
    http_method 
    = 
    "POST" 
    , 
    name 
    = 
    "greetings.multiply" 
    , 
    ) 
    def 
     
    multiply_greeting 
    ( 
    self 
    , 
    request 
    ): 
    return 
    Greeting 
    ( 
    message 
    = 
    request 
    . 
    message 
    * 
    request 
    . 
    times 
    ) 
    
   

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 query string (for example, yourApi?times=2 ), or the URL path (for example, yourApi/2 ). However, in order for your API to receive an argument value by using the URL path, you must also add the argument name to the API path as shown for the {times} argument in path='yourApi/{times} .

What's next

• Creating the API
• Creating an API implemented with multiple classes