An API is a remote procedure call (RPC) service that provides remote
methods accessible to external clients. Each backend 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 query string arguments, you use a
ResourceContainer
class for the mapping, instead of a simple Message
class.
Finally, you need to decorate the API service class and class methods, and you
need to define Message
classes for the requests and responses.
Creating the API
The following procedure shows how to decorate your code to create an API implemented in a single class. If you have a multi-class API, see Creating an API implemented with multiple classes. See Decorators for detailed information about all the available decorators.
To create an API:
Add the following required imports:
Define a subclass of
remote.Service
and decorate it with@endpoints.api
:Notice that your API name and the name of your service class don't need to be the same. The version number applies to the version of the API. The value that you enter becomes part of the path in the URL to your API. For more information on versions, see Handling API versioning.
Determine what data your method expects from the request and what data is returned, and create a
Message
class for the request body and response body:Note that if no arguments appear in the request body, such as in a
GET
request, you can omit theMessage
class for the request and simply use the valuemessage_types.VoidMessage
.If your request has path or query string arguments, replace your
Message
class with an appropriateResourceContainer
.For complete information on forming and using
Message
classes, see the documentation for the Google Protocol RPC response and requestMessage
classes.Create the method for your API, and decorate it with
@endpoints.method
:If your request has path or query string data, replace the request message type with an appropriate
ResourceContainer
.Add the code to serve your API, as described in Creating a web server.