At Acquia, we firmly believe that metadata is crucial in unlocking the power for you to organize and easily find the right content. Knowing that these details are consistent and precise for our customers is essential in our products and APIs. For better consistency and ongoing support of the Acquia DAM API v2.0, we’re planning on releasing a change that impacts supplying and retrieving empty metadata values.

What’s changing

This change only affects how empty-like values are treated. All of the following are considered empty-like:

• null
• []
• [null]
• [""] (empty or blank value, with only whitespace characters)

Note that what is considered empty-like is not changing, just how empty-like values are treated in the Acquia DAM API v2.0.

With this slated change, any supplied or returned empty-like metadata value will be coerced into an empty list ([]). This erases the distinction between various empty-like values and between unset metadata fields and fields previously set to an empty-like value. Dropping these distinctions will add clarity, as they’re typically not useful and can be confusing.

For example, when previously updating asset metadata to an empty value ([null]):

curl --request PUT \
     --url 'https://api.widencollective.com/v2/assets/{id}/metadata' \
     --header 'authorization: Bearer demo/abc123def456' \
     --header 'content-type: application/json' \
     --data '{ "fields": { "description": [null] } }'

This would produce the following metadata response when retrieving asset metadata:

"metadata": {
    "fields": {
        "description": [""]
    }
}

The change will produce the following response:

"metadata": {
    "fields": {
        "description": []
    }
}

Affected resources

• Create New Asset (when the metadata multipart/form-data field is supplied)
  • POST /v2/uploads
• List by Search Query (when the metadata expand parameter is supplied)
  • /v2/assets/search?expand=metadata
  • /v2/assets/search/scroll?expand=metadata
• Retrieve Asset by ID (when the metadata expand parameter is supplied)
  • GET /v2/assets/{id}?expand=metadata
• Retrieve Asset Metadata
  • GET /v2/assets/{id}/metadata
• Update Asset Metadata
  • PUT /v2/assets/{id}/metadata

How to test the new behavior

You can test this change in behavior now before it goes live by making use of an early access toggle. When making requests to the affected resources listed above, the following header can be supplied, which will ensure consistent empty metadata handling occurs:

x-widen-api-toggle: empty-metadata-handling

For example, when retrieving an asset by ID:

curl --request GET \
     --url 'https://api.widencollective.com/v2/assets/{id}?expand=metadata' \
     --header 'authorization: Bearer demo/abc123def456' \
     --header 'x-widen-api-toggle: empty-metadata-handling'