Deploying an API to a gateway

Prerequisites

Before you can deploy an API config on API Gateway, ensure that you have:

Prepared your development environment as described in Configuring your development environment.
Created an API.
Created an API definition.
Created an API config from your API definition.

Gateway ID requirements

Many of the gcloud commands shown below require you to specify the ID of the gateway, in the form: GATEWAY_ID. API Gateway enforces the following requirements for the gateway ID:

Must have a maximum length of 49 characters.
Must contain only lowercase letters, numbers, or dashes.
Must not start with a dash.
Must not contain an underscore.

Defining the endpoint of the deployed API config

When you deploy an API config to a gateway, API Gateway creates a unique URL for the gateway in the gateway.dev domain. Your API clients then use a URL in the form below to access the deployed API config:

https://GATEWAY_ID-HASH.REGION_CODE.gateway.dev

where GATEWAY_ID is the name of the gateway, HASH is the unique hash code generated when you deployed the API, and REGION_CODE is the code for the GCP region where you deployed the gateway.

For example:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

Deploy an API config to a gateway

Use the Google Cloud CLI to deploy an API config to a gateway. When you deploy the API config, you are required to specify the name of the API. If the gateway does not already exist for the API, then this command also creates it.

To deploy an API config to a gateway:

Validate the project ID returned from the following command to make sure that the gateway isn't created in the wrong project.
```
gcloud config list project
```
If you need to change the default project, run the following command and replace PROJECT_ID with the Google Cloud project ID in which you want to create the service::
```
gcloud config set project PROJECT_ID
```

View help for the gateway create command:

gcloud api-gateway gateways create --help

Run the following command to deploy the API config to the gateway:
```
gcloud api-gateway gateways create GATEWAY_ID \
  --api=API_ID --api-config=CONFIG_ID \
  --location=GCP_REGION --project=PROJECT_ID
```
where:
- GATEWAY_ID specifies the ID of the new gateway. If the gateway does not already exist then this command creates it.
- API_ID specifies the ID of the API Gateway API associated with this gateway.
- CONFIG_ID specifies the ID of the API config deployed to the gateway. You must specify an API config when creating a gateway.
- GCP_REGION specifies the GCP region for the deployed gateway.
  Note:
  Allowed values are:
  - asia-northeast1
  - australia-southeast1
  - europe-west1
  - europe-west2
  - us-east1
  - us-east4
  - us-central1
  - us-west2
  - us-west3
  - us-west4
- PROJECT_ID specifies the Google Cloud project ID.
As it is creating the gateway, gcloud outputs information to the terminal.

On successful completion, you can use the following command to view details about the gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

This command returns the following:

apiConfig: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
createTime: '2020-02-05T13:44:12.997862831Z'
defaultHostname: my-gateway-a12bcd345e67f89g0h.uc.gateway.dev
displayName: GATEWAY_ID
name: projects/PROJECT_ID/locations/GCP_REGION/gateways/GATEWAY_ID
serviceAccount:
  email: gateway-111111@222222-tp.iam.gserviceaccount.com
state: ACTIVE
updateTime: '2020-02-05T13:45:00.844705087Z'

Note the value of the defaultHostname property. This is the hostname portion of the gateway URL. To access an API config deployed to this gateway, you use a URL in the form:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev

The Google Cloud CLI takes many options, including those described in the gcloud Reference. In addition, for API Gateway, you can set the following options when creating a gateway:

--async: Return control to the terminal immediately, without waiting for the operation to complete.
--display-name=NAME: Specifies the display name of the gateway, meaning the name shown in the UI. Do not use spaces in the name. Use hyphens and underscores instead. The default value is GATEWAY_ID.
--labels=KEY1=VALUE1,KEY2=VALUE2,...: Specifies labels associated with the gateway.

Listing gateways

To list gateways for a specific project:

gcloud api-gateway gateways list --project=PROJECT_ID

This command returns output in the form:

GATEWAY_ID        LOCATION       DISPLAY_NAME     STATE     CREATE_TIME          UPDATE_TIME
my-gateway        us-central1    my-gateway       ACTIVE    2021-01-07T00:04:19  2022-05-21T00:33:46

To list gateways for a specific project and region:

gcloud api-gateway gateways list --location=GCP_REGION --project=PROJECT_ID

Use a filter expression to list the gateways associated with a specific API:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/*" \
  --project=PROJECT_ID

Or use this filter to list gateways for a specific API config:

gcloud api-gateway gateways list \
  --filter="apiConfig:projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID" \
  --project=PROJECT_ID

Use the project, region, and gateway IDs to obtain detailed information about the gateway, including the identity of the API config deployed to the gateway:

gcloud api-gateway gateways describe GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID

Updating a gateway

Update a gateway to:

Deploy a different API config to the gateway
Update the display name
Update the labels

Use the following gcloud command to update an existing gateway, where UPDATE_OPTIONS is replaced with the gateway option flag and value you wish to update:

gcloud api-gateway gateways update GATEWAY_ID \
  UPDATE_OPTIONS --api=API_ID --location=GCP_REGION --project=PROJECT_ID

For example, to update the API config deployed to the gateway:

gcloud api-gateway gateways update GATEWAY_ID \
  --api-config=NEW_CONFIG_ID --api=API_ID --location=GCP_REGION --project=PROJECT_ID

where NEW_CONFIG_ID specifies the new API config to deploy to the gateway.

For a complete list of available update flags and arguments, see the gcloud api-gateway gateways update reference or use the following command to view all update options:

gcloud api-gateway gateways update --help

Deleting a gateway

Use the following gcloud command to delete an existing gateway:

gcloud api-gateway gateways delete GATEWAY_ID \
  --location=GCP_REGION --project=PROJECT_ID