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`](https://docs.cloud.google.com/appengine/docs/python/tools/protorpc) class, and
one or more methods. When you define a method, you must also define
[`Message` classes](https://docs.cloud.google.com/appengine/docs/python/tools/protorpc#Working_with_Messages)
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.

> [!NOTE]
> **Note:** The `Message` classes aren't part of the exposed API, so clients don't need to know about them.

If a request has path or query string arguments, you use a
[`ResourceContainer`](https://docs.cloud.google.com/endpoints/docs/frameworks/python/decorators-reference.md.txt#using_resourcecontainer_for_path_or_query_string_arguments)
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](https://docs.cloud.google.com/endpoints/docs/frameworks/python/create-multi-class-api.md.txt).
See
[Decorators](https://docs.cloud.google.com/endpoints/docs/frameworks/python/decorators-reference.md.txt)
for detailed information about all the available decorators.

To create an API:

1. Add the following required imports:

   ```python
   import endpoints
   from endpoints import message_types
   from endpoints import messages
   from endpoints import remote
   ```
2. Define a subclass of `remote.Service` and decorate it with `@endpoints.api`:

   ```python
   @endpoints.api(name="echo", version="v1")
   class EchoApi(remote.Service):
   ```

   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](https://docs.cloud.google.com/endpoints/docs/frameworks/python/handling-api-versioning.md.txt).
3. Determine what data your method expects from the request and what data is
   returned, and create a
   [`Message` class](https://docs.cloud.google.com/appengine/docs/python/tools/protorpc#Working_with_Messages)
   for the request body and response body:

   ```python
   class EchoRequest(messages.Message):
       message = messages.StringField(1)


   class EchoResponse(messages.Message):
       """A proto Message that contains a simple string field."""

       message = messages.StringField(1)


   ECHO_RESOURCE = endpoints.ResourceContainer(
       EchoRequest, n=messages.IntegerField(2, default=1)
   )
   ```

   Note that if no arguments appear in the request body, such as in a `GET`
   request, you can omit the `Message` class for the request and simply use the
   value `message_types.VoidMessage`.

   If your request has path or query string arguments, replace
   your `Message` class with an appropriate
   [`ResourceContainer`](https://docs.cloud.google.com/endpoints/docs/frameworks/python/create_api.md.txt#using_resourcecontainer_for_path_or_query_string_arguments).

   For complete information on forming and using `Message` classes, see the
   documentation for the
   [Google Protocol RPC](https://docs.cloud.google.com/appengine/docs/python/tools/protorpc)
   response and request `Message` classes.
4. Create the method for your API, and decorate it with
   `@endpoints.method`:

   ```python
   @endpoints.method(
           # This method takes a ResourceContainer defined above.
           ECHO_RESOURCE,
           # This method returns an Echo message.
           EchoResponse,
           path="echo",
           http_method="POST",
           name="echo",
       )
       def echo(self, request):
   ```

   If your request has path or query string data, replace the request message
   type with an appropriate
   [`ResourceContainer`](https://docs.cloud.google.com/endpoints/docs/frameworks/python/decorators-reference.md.txt#using_resourcecontainer_for_path_or_query_string_arguments).
5. Add the code to serve your API, as described in
   [Creating a web server](https://docs.cloud.google.com/endpoints/docs/frameworks/python/api_server.md.txt).

## What's next

- [Creating an API implemented with multiple classes](https://docs.cloud.google.com/endpoints/docs/frameworks/python/create-multi-class-api.md.txt)
- [Decorators](https://docs.cloud.google.com/endpoints/docs/frameworks/python/decorators-reference.md.txt)