Search API resources using semantic search

This page applies to Apigee and Apigee hybrid.

You can easily find and view API resources registered in your API hub using Semantic search. With its AI-powered search engine, Semantic search can go beyond term "matching" and return 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.

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

Semantic search is enabled by default during the API hub provisioning process. You can however disable and enable the feature at any time. To enable or disable semantic search, do the following:

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

    Go to API hub

  2. Click Settings from the left navigation menu to open the Settings page.
  3. Click the Actions tab and go to the Semantic search section.
  4. Use the toggle to enable or disable semantic search.

    To enable semantic search, you must select a multi-region location which is used to store the search data.

Console

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.

API

To search your API hub resources using the API hub API, use the searchResources method:

      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.