Pass data to and from the backend service

When an API client makes a request to your API deployed on API Gateway, the client can pass any or all of the following information as part of the request:

Request headers
Query params
Form data
XML or JSON payloads
Request paths

In building its response to the API request, the backend service can return data to the API client, including:

Response headers
XML or JSON payloads

This document describes how this data is passed to and from the backend service.

How is request data passed to the backend service?

All data in the request from the API client is passed unchanged to the backend service. It is then up to the backend service to parse the request data as part of handling the request.

How is response data returned to the API client?

All data received in the response from the backend service is passed unchanged to the API client. It is then up to the API client to process any returned data in the response.

How is the request URL passed to the backend service?

The URL used to make a request to the backend service is controlled by the x-google-backend extension. This section describes the options for configuring the backend service URL.

Set the backend service address and path in the OpenAPI spec

In the OpenAPI spec that you use to create an API config, you use the x-google-backend extension to specify the URL of the backend service. For example, you specify the backend service in the form:

Backend	x-google-backend
Cloud Run functions	x-google-backend: address: https://`GCP_REGION`-`PROJECT_ID`.cloudfunctions.net/hello
Cloud Run	One of the following: x-google-backend: address: `APP_URL` x-google-backend: address: `DETERMINISTIC_URL`
App Engine standard environment	x-google-backend: address: https://`PROJECT_ID`.appspot.com

Backend

x-google-backend

Cloud Run functions

x-google-backend:
  address: https://GCP_REGION-PROJECT_ID.cloudfunctions.net/hello

Cloud Run

One of the following:

```
x-google-backend:
  address: APP_URL
```

x-google-backend:
  address: DETERMINISTIC_URL

App Engine standard environment

x-google-backend:
  address: https://PROJECT_ID.appspot.com

In these examples:

APP_URL specifies the actual URL of your Cloud Run service (the full path of the called API), also referred to as the non-deterministic URL. For example: https://hello-abc1def2gh-uc.a.run.app.
DETERMINISTIC_URL is the deterministic URL for your Cloud Run service backend.

Note: If you plan to use the deterministic URL to version your Cloud Run service backend, you must specify one of the following:

Open API 2.0: jwt_audience field under address in the x-google-backend section
Open API 3.0: jwtAudience field under address in the x-google-api-management section

The value of the jwt_audience or jwtAudience field should be the Cloud Run service hostname. For example, for OpenAPI 2.0:

...
  x-google-backend:
      address: https://VERSION_TAG---SERVICE_HOSTNAME/PATH
      jwt_audience: https://SERVICE_HOSTNAME
...

If the jwt_audience or jwtAudience field is not present, the field defaults to the value of the address field for the JWT audience claim. This can result in an unexpected JWT audience claim for Cloud Run if the revision tag URL is used for address and no jwt_audience or jwtAudience is specified.

In addition, the path parameter in the OpenAPI spec specifies the endpoint, or resource, supported by your API. You can specify an absolute path or one that uses path parameters:

Path	Path with parameters
paths: /hello:	paths: /hello/{name}:

Generate the backend service URL from an API request

As API Gateway handles a request from the API client, it takes the request URL sent by the API client and translates it into the URL used to make the request to the backend service. Exactly how this translation occurs depends on which path translation strategy you are using.

The path_translation option to the x-google-backend extension supports two path translation strategies: