Manage attributes

This page applies to Apigee and Apigee hybrid.

Overview

You can think of an attribute as metadata for a resource. For example, in the case of an API resource, the API can have an attribute called Target Users that specifies if the API is intended for public, private, or internal consumption. There are many other such attributes available.

Attributes are useful to you in the following ways:

You can filter your resource search results based on attributes. Therefore, having more attributes will make it easy for you to narrow down your search results.
You can create custom attributes and associate them to API hub resources.

API hub stores an attribute in the key-value format; where the key is the name of the attribute, and the value is the corresponding value of the attribute. And the value can be in any of the following formats:

String
Enum
JSON

The attributes can be of the following two types:

System attributes, which are predefined by API hub.
User attributes, which are defined by you.

System attributes

System attributes are predefined by API hub for each resource type. The list of such attributes, and their value definitions, can change from release to release of API hub. Examples of system attributes are; lifecycle stage, API compliance, API accreditation, SLO, and so on. These attributes may be mandatory or optional for a resource. If an attribute is mandatory for a resource, you must set the value of the attribute when you register the resource.

The values of Enum type system attributes can be immutable or mutable.

Immutable - You can't make any changes to the existing values. However, you can add new mutable values to the attribute. For example, the oas-version attribute will have the values 2.1, 3.0, and 3.1. You can't update these values, but you can add new custom values.
Mutable - You can add, edit, or delete the existing values. For example, the lifecycle-stage attribute can initially have values like Dev, Stage, UAT, or Prod. You can edit these existing values, and add new values.

View system attributes

Console

To view all the system attributes, in the Google Cloud console, go to the API Hub > Settings page. You can view all the existing system attributes in the System attributes tab.

REST API

To view all the system attributes of a resource issue a GET request to the following API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes

For more information about the API, see ListAttributes.

The following example shows the API call to get the system attributes for all the resources.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json" \
-X GET \
https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/attributes?filter=definition_type=SYSTEM_DEFINED

Edit a system attribute of type Enum

You can perform the following operations for a mutable value:

Add a new value
Update an existing value
Delete an existing attribute value

The examples in this section show how to update the allowed values of a system attribute of Enum type.

Console

To add a value for a system attribute, do the following steps:

In the Google Cloud console, go to the API Hub > Settings page.
This displays all the existing system attributes in the System attributes section of the Attributes tab.
Click Edit for the attribute to which you want add a value.
This opens the attribute's edit pane, which displays the existing attribute values.
To add a new value, click Add item, and then enter the new value you want to add.
Note: To delete an existing value, click Delete for the value that you want to delete. The Delete option is displayed only for the values that are mutable. Therefore, if the delete option isn't displayed for a value, you can infer that that value is immutable.
Click Save.

REST API

To update allowed values of a system defined attribute of Enum datatype, issue a PATCH request to the following API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes/ATTRIBUTE

For more information about the API, see UpdateAttribute.

The following example shows the API call to update the values of the Business unit attribute.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"allowed_values": [
{
"id": "bu1",
"display_name": "Business unit 1",
"description": "The API can be used by business unit 1"
},
{
"id": "bu2",
"display_name": "Business unit 2",
"description": "The API can be used by business unit 2"
},
{
"id": "bu3",
"display_name": "Business unit 3",
"description": "The API can be used by business unit 3"
}]}' \
-X PATCH https://apihub.googleapis.com/v1/projects/test-15/locations/us-central1/attributes/system-business-unit?update_mask=allowed_values

It's important to understand how API hub interprets the request payload for the UpdateAttribute API.

If the value you specify in the payload is already present, API hub checks if the value has been updated in the payload, and then overwrites the value if it's updated.
If the value isn't available in the payload, API hub interprets that value should be deleted, and deletes the value from API hub.
If a new value is available in the payload, API hub adds the new value to the attribute.

User defined attributes

User defined attributes are defined by you based on your requirements.

View user defined attributes

Console

To view all the user attributes, in the Google Cloud console, go to the API Hub > Settings page. You can view all the user attributes in the User defined attributes section of the Attributes tab.

REST API

To view all the user attributes of a resource issue a GET request to the following API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes

For more information about the API, see ListAttributes.

The following example shows the API call to get the user attributes for the API resource.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-type: application/json" \
-X GET \
https://apihub.googleapis.com/v1/projects/test-project-1/locations/us-central1/attributes?filter=definition_type=USER_DEFINED

Add a new user attribute

Console

To add a new user attribute, do the following steps:

In the Google Cloud console, go to the API Hub > Settings page.
This displays all the user attributes in the User attributes section of the Attributes tab.
Click Create attribute.
This opens the Add a new attribute pane.
Enter the following details:
- ID: Enter an unique identifier for the attribute.
  - If you leave the field empty, API hub automatically generates an unique ID for you.
  - If you manually want to enter a value, ensure that the value is unique across all the attributes.
- Name: Enter a name for the attribute.
- Description: Optionally, enter a attribute description.
- Maximum allowed values: Enter a number from 1 through 20. This setting specifies the maximum number of values that the attribute can have.
- Resource type: Select a resource type.
To add a new value for the Enum type, click Add item, and then enter the new value you want to add.
Note: To delete an existing value, click Delete for the value that you want to delete.
Click Save.

REST API

To add a new user attribute, issue a POST request to the following API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes?attribute_id=NEW_ATTRIBUTE_NAME

For more information about the API, see CreateAttribute.

The following example shows the API call to create the attribute-01 user attribute.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"  \
-d '{
"display_name" : "custom attribute",
"description" : "custom attribute details",
"definition_type" : "USER_DEFINED",
"scope" : "API",
"data_type" : "ENUM",
"allowed_values" : [
{
"id" : "value-1",
"display_name" : "Value 1",
"description" : "Value 1 test description",
"immutable" : false,
},
{
"id" : "value-2",
"display_name" : "Value 2",
"description" : "Value 2 test description",
"immutable" : false,
},
],
"cardinality" : 4,
"mandatory" : false
}' \
-X POST  https://apihub.googleapis.com/v1/projects/test-15/locations/us-central1/attributes?attribute_id=attribute-01

Edit a user attribute

You can perform the following edits on a user attribute:

Update the attribute name
Add new attribute value
Delete an existing attribute value

Console

To edit a user attribute, do the following steps:

In the Google Cloud console, go to the API Hub > Settings page.
This displays all the existing user attributes in the User attributes section of the Attributes tab.
Click Edit for the attribute you want to edit.
This opens the attribute's edit pane, which displays the existing attribute values.
You can edit the name, description, and maximum allowed values. For Enum types, you can add new values. To add a new value for an Enum type, click Add item, and then enter the new value you want to add.
Click Save.

REST API

To edit a user attribute, issue a PATCH request to the following API:

https://apihub.googleapis.com/v1/projects/PROJECT/locations/LOCATION/attributes/ATTRIBUTE

For more information about the API, see UpdateAttribute.

The following example shows the API call update the API Visibility user attribute.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "projects/test-15/locations/us-central1/attributes/API Visibility",
    display_name" : "API Visibility Updated", "allowedValues": [
    {
    "id": "internal",
    "displayName": "Internal",
    "description": "The API is visible internally in an organization"
    },
    {
    "id": "external",
    "displayName": "External",
    "description": "The API is visible externally in an organization"
    },
    {
    "id": "public",
    "displayName": "Public",
    "description": "The API is visible public in an organization"
    }
    ]}' \
    -X PATCH https://autopush-apihub.sandbox.googleapis.com/v1/projects/common-dev-15/locations/us-central1/attributes/API Visibility?update_mask=display_name,allowed_values

It's important to understand how API hub interprets the request payload for the UpdateAttribute API.

If the value you specify in the payload is already present, API hub checks if the value has been updated in the payload, and then overwrites the value if it's updated.
If the value isn't available in the payload, API hub interprets that value should be deleted, and deletes the value from API hub.
If a new value is available in the payload, API hub adds the new value to the attribute.