Manage dependencies

This page applies to Apigee and Apigee hybrid.

This document describes how to create and manage dependencies between registered APIs. Dependencies help you see the relationships between APIs. See Introduction to dependencies.

The UI lets you see at a glance the relationship between consumer and supplier APIs, where the consumer depends on a operation from the supplier. See Figure 1.

API hub dependencies UI. — **Figure 1.** The API dependency UI shows you consumer/supplier pairs, where a consumer operation depends on a supplier operation. You can easily drill down to see the details of each dependency. You can also filter the table by consumer and/or supplier operations.

Create a dependency

You can create a dependency entity with the REST API.

Console

To create a dependency:

In the Google Cloud console, go to the Supply chain page in API hub.
Go to API hub
Click Create Dependency.
Add a description of the dependency.
Under Select supplier resource, select Operation.
Note: To use external APIs to create dependencies, you must use the Dependencies API. Only through the API do you have the option of specifying an external API as the source. Click the Rest tab for more information about how to use the API.
Select the API that supplies the operation.
Select the API version of the API that provides the operation.
Select the operation that is supplied to the consumer. For example: GET-/items.
Under Select consumer resource, select Operation.
Select the API that consumes the operation from the supplier.
Select the version of the API that consumes the operation.
Select the operation that uses the supplied API. For example: GET-/categories
Optionally, provide values for any user-defined attributes that were defined in Settings.
Click Create. The new dependency appears in the Dependencies list page (Figure 1).

REST

To create a new dependency using the Create a dependency API:

curl -X POST 'https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/dependencies?dependency_id=DEPENDENCY_ID' \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H 'Content-Type: application/json' \
  --d '{
      "description": "DESCRIPTION",
      "supplier": {
          // Specify one of the following:
          "operation_resource_name": RESOURCE_NAME
          // OR
          "external_api_resource_name: RESOURCE_NAME"
      },
      "consumer": {
        // Specify one of the following:
        "operation_resource_name": RESOURCE_NAME
        // OR
        "external_api_resource_name: RESOURCE_NAME"
      }
  }'

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.
DEPENDENCY_ID: (Optional) The identifier of the dependency. If not provided, a system-generated ID will be used. The name must be a string of 4-500 characters, where valid characters are /[a-z][A-Z][0-9]-_.
DESCRIPTION: (Optional) A brief description of the dependency.
RESOURCE_NAME: (Required) Either the resource name of an operation in API hub or an external API, depending on which attribute you specify.

Operation resource names follow this format: projects/PROJECT/locations/LOCATION/apis/API/versions/VERSION/operations/OPERATION
Operation resource example: "projects/myproject/locations/us-central1/apis/payments-api/versions/locationv1/operations/getlocation".

External API resource names follow this format: projects/PROJECT/locations/LOCATION/externalApis/EXTERNAL_API

External API resource example: "projects/myproject/locations/us-central1/externalApis/petstore".

Sample response:

{
  "name": "projects/myproject/locations/us-central1/dependencies/user-to-pet",
  "consumer": {
      "displayName": "POST - /v2/user",
      "operationResourceName": "projects/myproject/locations/us-central1/apis/payments-api/versions/version1/operations/createuser"
  },
  "supplier": {
      "displayName": "POST - /v2/pet",
      "operationResourceName": "projects/myproject/locations/us-central1/apis/payments-api/versions/version1/operations/addpet"
  },
  "state": "VALIDATED",
  "description": "Dependency from user to pet API",
  "discoveryMode": "MANUAL",
  "createTime": "2024-04-17T19:33:31.664226Z",
  "updateTime": "2024-04-17T19:33:31.664226Z"
 }

Example REST

curl -X POST 'https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/dependencies?dependency_id=user-to-pet' \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H 'Content-Type: application/json' \
  --d '{
      "description": "Dependency from user to pet API",
      "consumer": {
          "operation_resource_name": "projects/myproject/locations/us-central1/apis/payments-api/versions/paymentv1/operations/createuser"
      },
      "supplier": {
          "operation_resource_name": "projects/myproject/locations/us-central1/apis/pet-api/versions/petstorev1/operations/addpet"
      }
  }'

List dependencies

This section explains how to list the dependencies. You can list all dependencies associated with all the versions for an API, or list all dependencies associated with a specific version.

Console

To list dependencies:

In the Google Cloud console, go to the Supply chain page in API hub. The list of known dependencies appears in the Supply chain page.
Go to API hub
In the Filter field, if needed, specify supplier and/or consumer operations to return relevant dependencies. The filter feature lets you find all dependencies linked with specified operations.

REST

To list all dependencies, use the List dependencies API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/dependencies"
      -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.

Sample output:

{
  "dependencies": [
      {
          "name": "projects/myproject/locations/us-central1/dependencies/user-to-pet",
          "consumer": {
              "displayName": "POST - /v2/user",
              "operationResourceName": "projects/myproject/locations/us-central1/apis/payments-api/versions/version1/operations/createuser"
          },
          "supplier": {
              "displayName": "POST - /v2/pet",
              "operationResourceName": "projects/myproject/locations/us-central1/apis/payments-api/versions/version1/operations/addpet"
          }
      }
  ]
 }

Get dependency details

This section explains how to get the details about an API dependency with the REST API. You can view consumer and supplier details, and you can view details about the dependency including errors that may indicate, for example, a broken dependency.

Console

To get a dependency:

In the Google Cloud console, go to the Supply chain page in API hub.
Go to API hub
In the Filter field, if needed, specify supplier and/or consumer operations to return relevant dependencies. The filter feature lets you find all dependencies linked with specified operations.
Locate a dependency of interest and click See Details.

REST

To view details of a dependency, use the Get dependency details API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/dependencies/DEPENDENCY_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.
DEPENDENCY_ID: The unique ID of the dependency.

Sample response:

{
  "name": "projects/myproject/locations/us-central1/dependencies/user-to-pet",
  "consumer": {
      "displayName": "POST - /v2/user",
      "operationResourceName": "projects/myproject/locations/us-central1/apis/payments-api/versions/version1/operations/createuser"
  },
  "supplier": {
      "displayName": "POST - /v2/pet",
      "operationResourceName": "projects/myproject/locations/us-central1/apis/payments-api/versions/version1/operations/addpet"
  },
  "state": "VALIDATED",
  "description": "Dependency from user to pet API",
  "discoveryMode": "MANUAL",
  "createTime": "2024-04-17T19:33:31.215978712Z",
  "updateTime": "2024-04-17T19:33:31.737505297Z"
}

Here's a sample response, where the error condition indicates the supplier operation was removed (a broken dependency):

{
  "name": "projects/common-dev-15/locations/us-central1/dependencies/user-to-pet",
  "consumer": {
      "displayName": "POST - /v2/user",
      "operationResourceName": "projects/common-dev-15/locations/us-central1/apis/payments-api/versions/2ff89c88-e8b6-48c4-a1c2-bdbb2a929bde/operations/createuser"
  },
  "supplier": {
      "displayName": "POST - /v2/pet",
      "operationResourceName": "projects/common-dev-15/locations/us-central1/apis/payments-api/versions/2ff89c88-e8b6-48c4-a1c2-bdbb2a929bde/operations/addpet"
  },
  "state": "VALIDATED",
  "description": "Dependency from user to pet API",
  "discoveryMode": "MANUAL",
  "createTime": "2024-04-17T19:33:31.215978712Z",
  "updateTime": "2024-04-17T19:33:31.737505297Z",
  {
    "error": "SUPPLIER_NOT_FOUND",
    "errorTime": 2024-05-18T20:23:42.465324Z
  }
}

Delete an API dependency

This section explains how to delete an API dependency.

Console

To delete a dependency:

In the Google Cloud console, go to the Supply chain page in API hub.
Go to API hub
In the Filter field, if needed, specify supplier and/or consumer operations to return relevant dependencies. The filter feature lets you find all dependencies linked with specified operations.
Locate a dependency of interest and click the delete icon to delete the dependency.

REST

To delete a dependency from API hub, use the Delete dependency API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/dependencies/DEPENDENCY_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -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.
DEPENDENCY_ID: The ID of the dependency to delete.

Edit a dependency

This section explains how to edit a dependency. The only editable attribute is the dependency description.

Console

To edit an API:

In the Google Cloud console, go to the Supply chain page in API hub.
Go to API hub
In the Filter field, if needed, specify supplier and/or consumer operations to return relevant dependencies. The filter feature lets you find all dependencies linked with specified operations.
Locate the dependency of interest and click See Details.
On the Dependency page, you can edit the description and the attributes. Use the edit icon to enable editing on those fields.
Click Save.

REST

To edit a deployment, use the Patch dependencies API:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/dependencies/DEPENDENCY_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      '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.
DEPLOYMENT_ID: The ID of the deployment to edit.
DESCRIPTION: The only editable attribute is the description.