Search for and filter APIs

This page applies to Apigee and Apigee hybrid.

This topic describes how to use Semantic Search powered by Vertex AI and filter-based search options to search for specific resources in API hub.

Search and filter.
Figure 1. API hub provides powerful natural language search and filter features.

You can easily find and view API resources registered in your API hub using Semantic Search. Semantic Search allows you to search all available API resources in your instance using a free-text search query. You can search across all entity types (APIs, API operations, specifications, and more.), or specify the entity type that you want to query.

With its Vertex AI search engine, Semantic Search can go beyond term "matching." Semantic Search returns results containing terms found anywhere in the detailed API resource entries that are semantically similar to the free text search queries entered.

Free-text search returns the following categories of results:

  • APIs: A list of APIs that match the search. For each API, the following details are provided:
    • The name of the API with a link to the API details page.
    • A brief description of the resource.
    • The name and email address of the resource owner.
  • Versions: A list of API versions that match the search. For each version, the following details are provided:
    • The names of the APIs associated with the version, with a link that takes you to the API details page.
    • The name of the API version, with a link that takes you to the version details page.
    • The description of the version and related metadata.
  • Specifications: A list of API specifications that match the search. For each specification, the following details are provided:
    • The names of the API associated with the specification, with a link that takes you to the API details page.
    • The name of the API specification, with a link that takes you to the version details page associated with the specification.
    • The description of the specification.
    • A link to the specification document.
    • The type of specification, such as OpenAPI spec.
  • Operations: A list of API operations that match the search. For each operation, the following details are provided:
    • The names of the API associated with the operation, with a link that takes you to the API details page.
    • The name of the operation, with a link that takes you to the version details page associated with the operation.
    • The description of the specification.
    • A link to the specification document that defines the operation.
    • A link to the version that includes the operation.
  • Deployments: A list of deployments that match the search. For each deployment, the following details are provided:
    • The name of the deployment.
    • The description of the deployment.
    • The deployment type. For example, Apigee hybrid.
    • A link to the version that includes the deployment.

To search for APIs containing a specific term:

  1. In the Google Cloud console, go to the API hub Semantic search page.

    Go to API hub

  2. Type a search query in the search box.

    For example, you could enter "Order management APIs" or "Spec file for wireless carrier settings".

    You can refine your search by using system attributes within your search query prompt. If you created user attributes when registering your APIs in API hub, you can also incorporate these attributes in your search query prompts.

  3. The Search results are categorized under the following tabs: APIs, Versions, Specifications, Operations, and Deployments. Click one of the tabs to see results for a category. The results display API resources that contain terms semantically similar to the search query you entered.
  4. Click the API resource name to view the detail page for the resource.
  5. To clear the current query, click Clear results.

You can also search your API hub resources using the API hub API. The searchResources method allows you to query your API hub resources using free text queries and filters.

You can use the following API call to search across your API hub resources: 

curl -X POST https://apihub.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:searchResources \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  -d '{
    "query":"QUERY",
    "filter":"resource_type = RESOURCE_TYPE"
   }'

Where:

  • PROJECT_ID is the ID of the host project for your API hub instance.
  • LOCATION is the location where your API hub instance is hosted.
  • QUERY is the free text query to be used in the search. The query can contain keywords related to any detail of the API hub resource, including display names, descriptions, or other metadata..
  • RESOURCE_TYPE is the optional filter specified for your search. You can specify one of the following API hub resource types as a filter:
    • Api
    • ApiOperation
    • Deployment
    • Definition
    • Spec
    • Version

For example: 

curl -X POST https://apihub.googleapis.com/v1/projects/{project-id}/locations/{location}:searchResources \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  -d '{
    "query":"dog status in the store",
    "filter":"resource_type = SPEC"
    }'

This call returns a paginated list of API hub resources, with resource-specific metadata.

For more information on free-text search with the API hub API, see the API reference documentation for Method:project.locations.searchResources.

Filter-based search options

You can refine the list of APIs displayed on the APIs page by using system attributes as search parameters. Customize the list of API resources displayed using one of the following:

Filter

Using the filter-based list search, you can streamline your APIs list based on a number of predefined parameters and system attributes associated with the resource. You can use the Match ALL or Match ANY options to customize your filtered view.

To specify filter options:

  1. In the Google Cloud console, go to the API hub APIs page.

    Go to API hub APIs

  2. Click in the Filter table field to filter the table. The Filter pane opens.
  3. Specify or select filter options. When you type in the Filter pane, a menu with filter options pops up that includes a list of system attributes that are relevant to the current context. For example, these are system attributes that you may see when filtering the APIs in the APIs page:
    • API name: The display name of the API
    • Business unit: The business unit responsible for an API
    • Team: The producing team responsible for an API
    • Documentation: A short link to the API documentation.

      • You'll see system attributes in the filter list in the APIs, Versions, and Specifications tables.

  4. After selecting a filter option, select a filter value from the Values list. Alternatively, you can enter a value for the filter attribute you select.
  5. To add an additional filter, click in the Filter table field to select from the available Operators and then select another filter attribute and value.

  6. The selected filter properties display the conditional logic that the filter query is using. You can select OR as an operator. If no operator is selected, the default is AND.

  7. To clear an individual filter, click the X on the filter. To clear all filters, click Clear all in the Filter pane.

Pagination

When there are multiple API resources, they may be displayed across multiple pages.

To customize the list display and navigate between pages:

  1. In the Google Cloud console, go to the API hub APIs page.

    Go to API hub APIs

    The APIs list page is displayed by default.

  2. From the APIs list, locate the pagination tools as shown in Figure 2:

    Pagination selections.
    Figure 2. Move back and forth through paginated results.
  3. Select the number of APIs to display per page.
  4. Click > Forward to go to the next page.
  5. Click < Back to go to the previous page.

What's next?