Designing and editing APIs

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Follow the instructions on this page to use Cloud Code to design and edit APIs.

Design APIs with Gemini Code Assist

Preview — Gemini Code Assist

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

You can use Cloud Code to design OpenAPI specification (OAS), version 3.0 APIs using Gemini Code Assist. Gemini Code Assist can include enterprise context for generative AI assistance in the API development process. Enterprise context uses the project's API hub APIs for context when generating new APIs and is available only with projects using API hub.

See Use Gemini Code Assist for information on setup steps to using the functionality in this section.

Note: At this time Gemini Code Assist supports designing APIs that combine new objects with existing objects (if enterprise context is enabled). It does not support scenarios for only reusing objects without creating any new objects.

To generate an API, follow these steps:

1. Click the magic wand in the left nav to use Gemini Code Assist to create a new API spec. Make sure to use this method to create API specs instead of Gemini Code Assist chat, which does not support all features and functionality when creating API specs.
   
2. Enter a prompt describing the new API in the Create an API spec input window.
   1. If desired, select a prompt template from the template chips shown. A prompt template provides a framework for your prompt to help you get started.
   2. Enter a prompt. See How to write effective API spec prompts.
      
      
3. Gemini Code Assist generates an OAS defining the API.
4. Review the spec:
   1. Click View code to review the spec in the code editor.
   2. The API renderer panel previews the API as it can be viewed by developers, including the API description and other documentation.
   3. If you already have APIs on API hub, that enterprise context is used to reuse objects from other APIs to this OAS and is enumerated in the OUTPUT panel:
      
   4. We appreciate your feedback! Provide feedback on the generated spec by clicking the thumbs-up or thumbs-down icon in the Swagger panel.
      
   5. If you'd like to edit preview prompts and regenerate the spec, click the prompt history arrows above the prompts to move between previous prompts.
      
5. Test the spec. Once the new spec is complete, you can test it using a mock server. See Test your API using a mock server.
6. Click Save to save your new API with a name of your choice.
7. To create an Apigee API proxy from this spec, click Create API proxy from the More menu. The creation process creates a proxy bundle. You should see the new proxy in the left menu list of your proxies. See the API proxy creation walkthrough that's integrated within Cloud Code for additional information on creating proxies from Cloud Code.
   

How to write effective API spec prompts

The accuracy and suitability of a generated API spec depends largely on the prompt that was provided to the model.

These are examples of good prompts:

• Create an API that allows customers to pay for an order using various payment methods such as credit cards and debit cards.
• Accept purchase orders for specialized coffee bean purchases through an API.
• We are a pizza company and want to create an online customized pizza delivery solution. Create an api to accept the pizza orders.
• 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.

These example show less effective prompts. Try to avoid prompts structured like these:

• Create an API for my store. This prompt contains too little information for the model to generate a complete and accurate spec.
• Create a new refund API that reuses the order object. You do not need to specify which objects Gemini Code Assist should reuse when creating new APIs; Gemini Code Assist automatically detects the best-suited objects to reuse.

Register the API with API hub

Once your API is reviewed and final, you can make it available to developers by registering it with API hub:

1. Click Register to API hub.
2. Follow the prompts to register the API. See Register APIs for information on registering with API hub and the information you need to provide.

Update your API hub APIs from Cloud Code

You can save a new version of your API hub specs when editing them from Cloud Code.

To save the spec as a new version, click the More options... button in the Swagger panel and Publish to API hub. Provide the new API version ID. You should see the new version appear in the version list for that API in the API hub list in Cloud Code.

Use the settings file to control Gemini Code Assist behaviors

This section explains how to manage whether and how Gemini Code Assist is available, from the settings file.

Disable or enable Gemini Code Assist

Once you've set up Apigee in Cloud Code (see Setting up Apigee in Cloud Code), you can add this line to your settings file to temporarily disable all Gemini Code Assist features:

"cloudcode.apigee.gemini.enable": false

Remove the line or set it to true (the default) to re-enable Gemini Code Assist.

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 in your API hub catalog that are in your API hub catalog that you are authorized to access. The deployment status of the API hub APIs is not considered.

Enterprise context is enabled by default.

You can:

• See the number of modifications included from enterprise context, if any, in the Swagger panel:
• See the included modifications in the Output panel:

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.

Edit APIs

To use Cloud Code to edit existing APIs that are part of your API hub catalog, follow these instructions. Changes you make in Cloud Code can be saved back to API hub.

These instructions are for users who are not using the Gemini Code Assist add-on for Apigee. For information on additional functionality that is available with Gemini Code Assist when designing and editing APIs, see Design an API with Gemini Code Assist.

Note: At this time, any changes to the API saved back to API hub must be saved as a new version.

To edit an API spec:

1. 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.
2. In the left nav, expand the API Hub tree.
3. Select the API and version to edit from the list.
4. Edit the spec in the editing panel. You can also view the API operations in the Swagger panel.
5. Optionally, test your API using a mock server.
6. Save the changes as a new version with the More button in the Swagger panel and then Publish to API hub. Confirm or update the version when prompted and save the changes back to API hub. You should see the new version appear in the version list for that API in the API hub list in Cloud Code.

Test your API 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.

Note: The local mock server might not work correctly when using VS Code Remote Explorer. Also, occasionally the local mock server cannot start. In that case, it will not be available in the drop-down list.

To use the local mock server:

1. Select the local mock server (development server) in the Servers dropdown.
   
2. Open a path and click Try it out.
   
3. Fill out any request parameters and click Execute.
   
4. You can also submit requests using curl from a prompt. Use the server address and port from the Servers dropdown.

Use a remote mock server

A remote mock server provides you with 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 before it is in production. Remote mock servers can only be used with APIs that are registered in API hub.

At this time remote mock servers can be created in Google Cloud. Google Cloud 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; you are responsible for any resulting costs and maintenance on those after creation. You are also responsible for deleting them once they are no longer needed. See What is Cloud Run?, Managing Services, and the Artifact Registry documentation.

Important: Once you create a Google Cloud remote mock server you are responsible for any resulting costs from its use, managing it, and removing it once it's no longer needed. See https://cloud.google.com/run/pricing for pricing information, including information on any free tier options.

To deploy a remote mock server:

1. Select Deploy mock server (Google Cloud) from the More menu.
2. If your API is not already registered in API hub, register it when prompted.
3. Specify details for the remote mock server: Project ID, Server Name, and Region and 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.
4. The remote mock server generation requires several minutes. You can watch the progress in the Google Cloud OUTPUT panel.
5. Once the remote mock server creation is complete, you'll see the remote server URL in the Swagger panel server list and the OUTPUT panel.
6. 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:

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

Use these steps to manage deployed remote mock servers:

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