Manage versions

This page applies to Apigee and Apigee hybrid.

This topic explains how to create and manage API versions. To learn about versions, see Versions overview.

Add a version to an API

You can add an API version to an existing API in the console or with the REST API.

Console

To add a new version:

In the Google Cloud console, go to the API hub page.
Go to API hub
Click APIs.
Locate the API you wish to version. Use Filter to specify keywords to filter the list of APIs. If needed, use Search to locate an API.
Click an API to view its details.
Under the Versions tab, click Add Version.
Specify version details in the Add a new version form. You must provide a display name. The other attributes are optional. For more information on attributes, see Manage attributes.
- Name: (Required) You must supply a display name.
- Description: Add a description of the version.
- Life Cycle: Select the life cycle stage of the API.
- Compliance: Select a compliance attribute.
- Accreditation: Select an accreditation attribute.
- Documentation: Enter the URL to documentation for the API.
- Add a Specification file: Import an API specification file to associate with the version. See Add an API spec to a version.
- Link to a deployment: Select one or more deployments to associate with the API.
- User-defined attributes: User-defined attributes are attributes that you define based on your organizational or team needs. See User attributes.
Click Create.

REST

To add a new version using the Create an API version API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions?version_id=VERSION_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X POST -H "Content-Type: application/json" \
  '{
    "display-name": "DISPLAY_NAME",
    "description": "DESCRIPTION"               # description is an optional attribute
    }'

Replace the following:

HUB_PROJECT: The name of your API hub host project. The host project was selected when API hub was provisioned.
HUB_LOCATION: The location of the host project. The location was chosen when API hub was provisioned.
API_ID: The unique ID of the API resource to add the version to.
VERSION_ID: (Optional) The unique identifier of the API version. If not provided, a system-generated ID will be used. The name must be a string of 4-63 characters, where valid characters are /[a-z][0-9]-/.
DISPLAY_NAME: (Required) The display name of the version. You can use any name you wish.
DESCRIPTION: (Optional) You can add a number of optional attributes to describe the version, including a description, an owner name, a link to documentation, and more. These optional attributes are listed and described in the Version resource definition.

Sample output:

{
  "name": "projects/myproject/locations/myproject/apis/docs-api-1/versions/myversion1",
  "displayName": "My Version 1",
  "createTime": "2024-04-02T18:48:41.162360Z",
  "updateTime": "2024-04-02T18:48:41.162360Z"
}

List API versions

This section explains how to list the versions associated with a registered API.

Console

To view all the versions associated with a registered API in the console:

In the Google Cloud console, go to the API hub page.
Go to API hub
Click APIs.
Locate the API you wish to inspect. Use Filter to specify keywords to filter the list of APIs. If needed, use Search to locate an API.
Select an API.
Versions are listed in the Versions table on the API details page.

REST

To view all the versions associated with a registered API, use the List API versions API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -H "Content-Type: application/json"

Replace the following:

HUB_PROJECT: The name of your API hub host project. The host project was selected when API hub was provisioned.
HUB_LOCATION: The location of the host project. The location was chosen when API hub was provisioned.
API_ID: The unique ID of the API resource.

Sample output:

{
  "versions": [
    {
      "name": "projects/myproject/locations/us-central1/apis/streetcarts-test/versions/streetcarts-testv1",
      "displayName": "Streetcarts Test v1"
    }
  ]
}

Get API version details

This section explains how to get the details about an API version, including its attributes, operations, deployments, and specification files.

Console

To view version details in the console:

In the Google Cloud console, go to the API hub page.
Go to API hub
Click APIs.
Locate the API you wish to inspect. Use Filter to specify keywords to filter the list of APIs. If needed, use Search to locate an API.
Select an API.
In the Versions table, click a version to see the version details page.

REST

To view details of a version using the Get API version details API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Replace the following:

HUB_PROJECT: The name of your API hub host project. The host project was selected when API hub was provisioned.
HUB_LOCATION: The location of the host project. The location was chosen when API hub was provisioned.
API_ID: The unique ID of the API resource.
VERSION_ID: The unique ID of the version.

Sample output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/specs/docs-spec-1"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcarts_testv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Delete an API version

This section explains how to delete an API version associated with an API resource.

Console

When you delete a version in the UI, all of the underlying specifications associated with the version (if any) are deleted.

To delete a version:

In the Google Cloud console, go to the API hub page.
Go to API hub
Click APIs.
Locate the API that includes the version you wish to delete. Use Filter to specify keywords to filter the list of APIs. If needed, use Search to locate an API.
Select an API.
In the Versions table, find the version you wish to delete.
From the Actions menu (the right side of the row containing the version), click Delete.

REST

By default, a version can only be deleted if all underlying specifications are deleted. If you want to delete all specifications under a version in one step, set the force query parameter to true in the Delete REST API.

To delete a version using the Delete API version API:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID'

Replace the following:

API_PROJECT: The name of your API hub host project. The host project was selected when API hub was provisioned.
API_LOCATION: The location of the host project. The location was chosen when API hub was provisioned.
API_ID: The unique ID of the API resource.
VERSION_ID: The ID of the version to delete.

To delete a version and all underlying specifications, set the force query parameter to true. For example:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID?force=true'

Edit a version

Console

To edit a version:

In the Google Cloud console, go to the API hub page.
Go to API hub
Click APIs.
Use Filter to specify keywords to filter the list of APIs. If needed, use Search to locate an API.
Select an API.
In the Versions table, locate the version you wish to edit.
Select Edit from the Actions menu at the right side of the version row. You can also access the edit feature by clicking Edit Version in the version detail page. To reach the details page, just click on a version in the version table.
After making edits, click Save to save your changes. For a description of the editable attributes, see the version resource description in the REST API reference.

REST

To edit a version with the REST API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID?updateMask=LIST_OF_ATTRIBUTES"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json" \
    '{
      "display-name": DISPLAY_NAME,  # Use the request body to specify attribute changes
      "description": "DESCRIPTION"

    }'

Replace the following:

HUB_PROJECT: The name of your API hub host project. The host project was selected when API hub was provisioned.
HUB_LOCATION: The location of the host project. The location was chosen when API hub was provisioned.
API_ID: The unique ID of the API that has the version you wish to edit.
VERSION_ID: The ID of the version to edit.
DESCRIPTION: You can add other editable attributes in the request body, like the description and others. The editable attributes are listed in the Apigee hub API reference. the Patch version API.
LIST_OF_ATTRIBUTES: A comma-separated list of fully qualified attribute names. For example: ?updateMask="description".

Sample output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts-test/versions/streetcarts-testv1",
  "displayName": "Streetcarts Test v1",
  "description": "This is a revision of the test version.",
  "documentation": {},
  "createTime": "2024-04-18T19:57:11.870761Z",
  "updateTime": "2024-04-18T20:23:42.465324Z"
}