In this part of the tutorial, you'll create a backend API with methods serving
two different HTTP
- A HTTP
GETrequest that returns a list of hardcoded greeting objects.
- A HTTP
GETrequest that includes the integer 0 or 1 in the path to specify a particular greeting.
You can checkout the code for this sample using git, or you can browse the sample on github
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git cd python-docs-samples/appengine/endpoints
Coding a backend with a simple HTTP
app.yaml configures the endpoints API URL handler:
main.py file imports the
protorpc libraries need to
create a backend API:
Then, the message classes are defined. These messages are used to define the requests and responses for the API:
Note that the sample also defines a hard-coded list of messages. This is so that the sample doesn't have to use a database and keeps things simple.
Next, the sample defines the API service. The API service defines and implements the methods that are available for the API. This API has two methods:
list_greetingsmethod returns the hardcoded list of greetings.
get_greetingmethod returns a single greeting from the list of greetings given an index.
Finally, the sample defines the API server which is responsible for routing requests to an individual service.
Running and testing your backend API
To run and test the backend you just created:
Start a new Chrome session as described in How do I use Explorer with a local HTTP API and specify
localhost:8080). Alternatively, you can use Firefox and temporary disable mixed content blocking.
In the project directory, start the development server:
When the backend is running successfully, a message similar to this one is displayed:
INFO 2013-10-07 19:41:16,687 admin_server.py:117] Starting admin server at: http://localhost:8000
In your browser, visit this URL:
This opens up the API Explorer for your backend. Notice the list of APIs displayed with Greeting API in that list.
Click greeting to display the available methods. Click greeting.greetings.get to display the Explorer form for it:
The simple backend has two "canned" messages in an array. Get the first message by entering a value of
0in the Id text box, then click Authorize and execute.
Notice the display of the request and response. In the Response, you'll see the OK result and the returned message, hello world!.
Enter a value of
1in the Id text box, then click Authorize and execute; this time the message is goodbye world!.
The Greeting message class is defined for the requests coming into the
greetings.get methods and the responses returned by them.
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.
greetings.list method returns several Greetings, so we use a
GreetingCollection message class that supports this.
The name and version of the API is specified in the class decorator
@endpoints.api(name='greeting', version='v1'). A complete list of decorator
arguments is provided in the topic Defining the
Notice that a class used for the API must be a
ProtoRPC service class, as shown above
in the line
class GreetingApi(remote.Service). (An Endpoints API is an RPC
service that provides remote methods accessible to external clients.)
Notice the difference in the API method decorators in the
get methods. The
list method supports GET requests with no
arguments, and therefore specifies the predefined
for the request message. The
get method supports a request containing
an argument in the URL, so it must specify a
In both method decorators, we supply the path to specify a location at which the
method serves requests. The value specified is appended to the API path, for
example, if the value
foo is specified, the path is
greetings.get, the path is
required or else your API method won't receive the incoming request argument.
Finally, code is provided to create the API server. You could optionally do this in a separate module if you wish. For more information, see Creating an API Server.
Next, you will add a simple HTTP
Continue to Writing the API: a Simple POST.