Creating an API

Prerequisites

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

• Prepared your development environment as described in Configuring your development environment.

API ID requirements

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

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

Creating an API

To create an API:

1. Validate the project ID returned from the following command to make sure that the service 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

   If your project ID contains a colon (:), see Domain-scoped projects for additional details about creating an API in your project.

2. View help for the apis create command:

   gcloud api-gateway apis create --help

3. Run the following command to create the API:

   gcloud api-gateway apis create API_ID --project=PROJECT_ID

   where:

   • API_ID specifies the ID of the new API. See API ID requirements for API naming guidelines.
   • PROJECT_ID specifies the Google Cloud project ID.

   As it is creating the API, API Gateway outputs information to the terminal.

4. On successful completion, you can use the following command to view details about the new API:

   gcloud api-gateway apis describe API_ID --project=PROJECT_ID

   This command returns the following:

   createTime: '2020-02-29T21:52:20.297426875Z'
   displayName: API_ID
   managedService: MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
   name: projects/PROJECT_ID/locations/global/apis/API_ID
   state: ACTIVE
   updateTime: '2020-02-29T21:52:20.647923711Z'

gcloud options

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 an API:

• --async: Return control to the terminal immediately, without waiting for the operation to complete.
• --display-name=NAME: Specifies the display name of the API, meaning the name shown in the UI. Do not use spaces in the name. Use hyphens and underscores instead. The default value is API_ID.
• --labels=KEY1=VALUE1,KEY2=VALUE2,...: Specifies labels associated with the API config.
• --managed-service: Specifies a pre-existing managed service (for example, an existing Endpoints service) for the API.

Domain-scoped projects

If your project is scoped to your domain, the project ID includes the name of the domain followed by a colon (:), for example, example.com:my-project. You must provide a valid managed service when creating an API in a domain-scoped project.

If using gcloud, provide the managed service name using the --managed-service flag, as described in gcloud options.

Note: Scoping projects to a domain is a legacy feature. You cannot create new domain-scoped projects.

Listing APIs

To list all APIs in a project:

gcloud api-gateway apis list --project=PROJECT_ID

This command returns output in the form:

NAME                                              DISPLAY_NAME  MANAGED_SERVICE                          STATE
projects/PROJECT_ID/locations/global/apis/API_ID  API_ID        MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog  ACTIVE

Use the project ID and API ID to obtain detailed information about the API:

gcloud api-gateway apis describe API_ID --project=PROJECT_ID

Updating an API

After creation, you can update the labels and display name of an existing API. Use the following gcloud options to update an existing API:

• --display-name
• --update-labels
• --clear-labels
• --remove-labels

For example:

gcloud api-gateway apis update API_ID --project=PROJECT_ID \
  --update-labels=a=1,b=2

Use the following command to view all update options:

gcloud api-gateway apis update --help

Deleting an API

To delete an API you must:

• Delete the API configs associated with the API.
• Delete the API.

Note: If you deployed an API config to a gateway, then deleting the API causes the gateway to stop serving traffic. However, you are not required to delete the gateway. Instead, you can deploy an API config from a different API to the gateway.

To delete an API:

1. Determine the list of API configs associated with the API:

   gcloud api-gateway api-configs list --api=API_ID --project=PROJECT_ID

2. Delete each API config associated with the API:

   gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

3. Delete the API:

   gcloud api-gateway apis delete API_ID --project=PROJECT_ID

What's next

• Creating an API config