Acquia Developer Portal Logo

New Faceted Asset Search

  • 4 minute read

Facets are now included in the Asset Search endpoint in version 2.0 of the Acquia DAM API. This new response data can help power integrations that wish to build a more rich search experience ranging from simple refinements to a fully featured faceted navigation.

What are facets?

At their core, facets describe the aspects of the items contained in a result set. With these helpful descriptions, items in a result set can be easily refined. This helps users search for more specific and relevant items in a practical manner. This functionality is also a great method for content discovery when used in conjunction with query-based filtering. This is even more true when dealing with a large result set.

For example, let’s assume we’re an online retailer that sells phones. We want our users to be able to quickly search to find their perfect new phone. But we have a very large inventory with dozens of manufacturers, models, sizes, and colors. Being able to facet on each of these discriminating aspects would allow shoppers to quickly and easily drill down to find only the small yellow phone of their dreams.

What’s changed

The existing Asset Search endpoint now accepts another optional query parameter, facet, which is a comma-delimited list of the specific facet types that should be returned in the search response. If this query parameter is omitted in the request, facets will not be included in the response.

Valid facet types are:

Example:

# ?facet=file_types,categories,metadata
curl --request GET \
     --url 'https://api.widencollective.com/v2/assets/search?facet=file_types,categories,metadata' \
     --header 'authorization: Bearer wac_demo_abc123def456'

This produces the following response with a new facets field (or null if no facet types were requested):

{
  "query": null,
  "sort": "-created_date",
  "query_explained": "",
  "sort_explained": "Created date (descending)",
  "include_archived": false,
  "include_deleted": false,
  "facets": {
    "file_types": [
      {
        "name": "IMAGE",
        "search_query": "ft:(IMAGE)",
        "count": 75
      },
      {
        "name": "VIDEO",
        "search_query": "ft:(VIDEO)",
        "count": 25
      }
    ],
    "categories": [
      {
        "id": "3a2de716-d13a-433e-8917-4bb15c920b66",
        "name": "Brand Photos",
        "path": "Brand Photos",
        "search_query": "cat:(Brand Photos)",
        "count": 100
      }
    ],
    "metadata": [
      {
        "display_key": "size",
        "display_name": "Size",
        "values": [
          {
            "value": "small",
            "search_query": "size:(small)",
            "count": 60
          },
          {
            "value": "medium",
            "search_query": "size:(medium)",
            "count": 30
          },
          {
            "value": "large",
            "search_query": "size:(large)",
            "count": 10
          }
        ]
      }
    ]
  },
  "item_type": "asset",
  "total_count": 100,
  "offset": 0,
  "limit": 10,
  "items": [...]
}

In the facets field response object, the corresponding requested facet types will be present (or null if omitted in the request). Each facet type field will contain a list of any applicable values with a count of the assets matching the values. A maximum of 25 values will be returned for each facet type, and each value must have a count of at least 1.

The metadata facet type contains a slightly different response, as each item in the list corresponds to a singular metadata field, each of which contains a list of values.

Every returned value contains a helper search_query field that can be directly supplied to subsequent asset search requests for simplified search refinement. Advanced uses with other quick search options are also valid.

Given the example response above, a subsequent search could be performed, this time with a search_query value used from a previously returned facet:

# ?query=ft:(VIDEO)&facet=file_types,categories,metadata
curl --request GET \
     --url 'https://api.widencollective.com/v2/assets/search?query=ft:(VIDEO)&facet=file_types,categories,metadata' \
     --header 'authorization: Bearer wac_demo_abc123def456'

In this scenario, a refinement was made and only assets with a file type of VIDEO will be returned. Also, since the facet query parameter was supplied, further facets will be included in the response. Integrations can use this method to easily create a rich faceted search experience.

Finally, this new facet functionality is available when initiating a scrolling search request, but facets will not be included while performing subsequent scroll requests using a scroll_id.

More Like This