Designing and editing APIs

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

This page provides instructions on how to design and edit APIs in Apigee in Cloud Code, leveraging Gemini Code Assist to accelerate API specification creation, editing, and management.

Before you begin

Before using the functionality in this guide:

Ensure you have completed the setup steps for Setting up Apigee API Management in Cloud Code for VS Code, including Using Gemini Code Assist with Apigee.
Make sure your user account has the required roles listed in Required roles to use Gemini Code Assist in Apigee for each task.

Write effective API spec prompts

You'll prompt Gemini Code Assist in Apigee when creating and editing API specs. The accuracy and suitability of generated API specs depends largely on the prompts provided to the model.

To write effective API spec creation and editing prompts:

With Gemini Code Assist Chat, always use the Apigee handle (@Apigee) at the start of your prompts to create or edit API specs. The Apigee handle allows you to access the Apigee tool which includes the robust and feature-rich API spec development features described in this guide.
Use natural language: Phrase your prompts as if you're addressing a person who will create the spec.
Be specific: Provide exact requirements where possible, such as that your dental office scheduling API needs to include multiple appointment types and multiple dental office locations.
Leverage enterprise context without specifying object names: Gemini Code Assist intelligently detects and reuses existing schemas, metadata, and security definitions from your API hub catalog. While you don't need to specify exact object names, you can hint at this capability by including phrases like Use API Hub or Leverage Enterprise Context in your prompt.
Use follow-up prompts to iterate on your APIs: You can use prompts like "Remove the locations entity from this API" to make changes to an API.

These are examples of less and more effective prompts for creating and editing API specs:

Less effective prompt	Prompt explanation	Better prompt(s)
"Create an API for my store."	This prompt contains too little information for the model to generate a complete and accurate spec.	"Create an API for my store for customers to check the availability of products and add items to their shopping cart." "Create an API that allows customers to pay for an order using various payment methods such as credit cards and debit cards."
"Create a new refund API that reuses the order object."	Do not specify which objects Gemini Code Assist should reuse when creating APIs; Gemini Code Assist automatically detects the best-suited objects to reuse.	"Create a new refund API that allows customers to request a refund for a previous order."
"Create an API for a delivery service."	The generated API will be too generic.	"We are a pizza restaurant and want an online customized pizza delivery solution. Create an api to accept the pizza orders with pizza size and toppings." "API for food delivery business. Customers can order a combination of pizza, burgers, or sandwiches in a single order. Each of those food types have its own schema. Pizzas have toppings and size. Burgers have toppings and patty type. Sandwiches have bread type, meat type, veggies, cheese, and custom instructions."

Design APIs with Gemini Code Assist

You can use Gemini Code Assist in Cloud Code to design OpenAPI specification (OAS), version 3.0 APIs. The designed APIs can include your enterprise context when generating new APIs and is available only with projects using API hub.

See Before you begin for information on set up steps for using the functionality in this section.

To generate a new API with Gemini Code Assist, follow these steps:

Use one of these methods to access the API spec creation prompt:
- From Gemini Code Assist: Chat: In the chat window, enter the Apigee handle, @Apigee, and select the Apigee tool.
- From Apigee in Cloud Code: Click the magic wand in the row for Apigee. This loads Gemini Code Assist: Chat. Invoke the Apigee tool with @Apigee to start spec creation.
Select Create API specification from the Apigee tool options.
Complete the prompt with a description of your new API. See Write effective API spec prompts. (Do not copy and paste over the @Apigee handle. Instead, complete the prompt by typing or pasting in the text after the handle.)
Submit the prompt.
Gemini Code Assist generates an OAS defining the API. (This process can take up to a minute.) If your API hub includes other APIs, the new OAS might incorporate objects and context from your catalog. The contextual chat summary provides information on the generated API and sources used.
Review the generated spec. Both the YAML code spec and Swagger panel for the new API show automatically in tabs.
Once the new spec is complete, you can test it using a mock server. See Test your API using a mock server.
To save the new API to your API hub catalog, see Publish APIs to API hub.
To create an Apigee API proxy bundle from this spec, see Save APIs as API proxy bundles.

Edit APIs

You can edit APIs you've saved locally or from your API hub catalog. Changes you make in Cloud Code can be saved to API hub or saved as an Apigee API proxy bundle.

Edit an API spec from API hub

To edit an API spec that is stored in your API hub catalog:

Make sure that the project you've selected in Cloud Code is the project with the API hub catalog containing the API you want to edit.
In the left nav, expand the API Hub tree in the Apigee section.
Select the API and version to edit from the list.
View the API operations in the Swagger panel. Click View code in the Swagger panel to open the YAML file in an editing tab.

Edit an API spec that is stored locally

To edit an API spec that is stored locally, open the API spec file in Cloud Code. You can manually update the spec, or use Gemini Code Assist Chat to iterate on the spec.

Iterate on API specs using Gemini Code Assist Chat

You can make changes to an existing API spec using Gemini Code Assist Chat:

Load the spec file into Cloud Code following the instructions for either an API spec from API hub or a local API spec file.
Make sure the YAML file containing the spec is the currently active tab in your editor.
In the Gemini Code Assist chat window, enter the Apigee handle, @Apigee, and select the Apigee tool.
Enter the spec update prompt. See Write effective API spec prompts for guidance.
Optionally, test your API using a mock server.
To save the new API to your API hub catalog, see Publish APIs to API hub.
To create an Apigee API proxy bundle from this spec, see Save APIs as API proxy bundles.

Publish APIs to API hub

If you are using API hub, you can make your APIs available to other developers by registering them with API hub:

In the Swagger panel for a new or edited API spec, click Publish to API hub.
In the form, provide metadata for the API to improve its discoverability and organization of APIs within your API hub catalog. Most fields are autopopulated from the API spec, but you can change the values. See Register an API for information on registering with API hub and the information you need to provide.
- API Display Name (Required): A name of the API, visible to other developers.
- API Description (Optional): A description of the API for internal/developer reference.
- API Owner Name (Optional): The name of the API owner.
- API Owner Email (Optional): The owner's email address.
- API Version (Required): The API version.
- Lifecycle Stage (Optional): Select a stage from the list.
Click Publish to publish the API to API hub.
After a short delay, your changes should be visible in the API Hub tree in the Apigee section of Cloud Code.

Test APIs using a mock server

You can test your API using either a local mock server or a Google Cloud-based remote mock server. The local mock server is installed and available by default while you must set up and manage Google Cloud mock servers.

Use the local mock server

The local mock server accepts requests to this API and emulates responses. It is usable only during the current session by the current user. However, unlike the remote mock server, it requires no setup or management and incurs no costs.

Also, local mock servers:

Do not work when using Cloud Shell Editor or Cloud Workstations.
Might not work correctly when using VS Code Remote Explorer.

To use the local mock server:

Select the local mock server in the Servers dropdown (if not already selected):
Open a path in the Swagger panel and click Try it out.
Fill out any request parameters and click Execute.

Use a remote mock server

A remote mock server provides the ability to create a persistent mock server instance that, unlike the local mock server, can be shared with and used by others within your organization to test the new API. Remote mock servers can only be used with APIs that are registered in API hub.

Remote mock servers do not automatically update for any changes you make to the API after deploying the mock server, so wait to add the mock server until you have fully created the API.

Deploying a Google Cloud remote mock server creates a new Cloud Run service. It builds a container image for the mock server using Cloud Build and uploads the container image to Cloud Artifact Registry in your Google project. See What is Cloud Run?, Managing Services, and the Artifact Registry documentation.

You can either use the default service account or provide a more restricted service account to deploy the Cloud Run application to. See Manage Cloud APIs and Cloud Client Libraries in Cloud Code for VS Code for information.

To deploy a remote mock server:

Select Deploy mock server from the Swagger panel.
If your API is not already registered in API hub, register it when prompted.
Specify details for the remote mock server: Server Name, Secure Server, Service Account (leave empty to use the default service account), and whether to add the server URL to the API spec. Click Create to create the remote mock server.
Important: Do not create multiple remote mock servers with the same name, even though the user interface will not prevent you from doing so at this time.
Remote mock server generation requires several minutes. You can watch the progress in the Cloud Code OUTPUT panel and through the notification pop up in the bottom right corner of their VS Code.
Once the remote mock server creation process is complete, you'll see the remote server URL in the Swagger panel server list and the OUTPUT panel.
To use the mock server, open a path and click Try it out.

Fill out any request parameters and click Execute.

You can also submit requests using curl from a prompt. Use the server address and port from the Servers dropdown.

To share access to the mock server with other users:

Give other users the invoker role for the deployed service. See Authenticate developers.
When making the request to the mock server, users follow the instructions in Test your private service.

To manage deployed remote mock servers:

Go to Apigee API hub.
Find the API to see all the deployments for the API, which includes any remote mock servers.
Use the Resource URL to go the deployment and manage it by stopping, deleting, and performing other actions on the mock server.

Save APIs as API proxy bundles

You can save your API as an Apigee API proxy bundle so that you can work on it within your Apigee local development environment. For information on working with API proxies in Cloud Code, see Develop API proxies.

Click Create API proxy bundle in the Swagger panel.
In the prompt field, name your API proxy and continue.
Your API proxy appears in the Apigee left menu in your local workspace, under apiproxies.

Control enterprise context in spec generation

OAS generation can include schema, metadata, and security definitions from your organization's other APIs. The process finds similar APIs using the object names and descriptions. The deployment status of the API hub APIs is not considered.

Enterprise context is enabled by default.

To disable enterprise context for new spec generation, add these lines in the settings.json file after "cloudcode.apigee.gemini.enable": true:

"cloudcode.apigee.gemini.options": {
         "enterpriseContext": {
           "enabled": false,
           "includeMetadata": false,
           "includeSchema": false,
           "includeSecurity": false
         }
     }

Where:

enabled specifies whether enterprise context is enabled overall. Set to false to disable enterprise context.
includeMetadata controls whether metadata context is included. This setting includes or excludes metadata from other APIs in API hub. includeMetadata is only applicable when enabled is set to true.
includeSchema controls whether schema context is included. This setting includes or excludes schema information from other APIs in API hub. includeSchema is only applicable when enabled is set to true.
includeSecurity controls whether security-related context is included. This setting includes or excludes security information from other APIs in API hub. includeSecurity is only applicable when enabled is set to true.