New Download Links

June 13, 2023
3 minute read

Developers at Acquia have recently been busy architecting a new download service. The goal of this shared service is to ensure that downloading files will be more consistent and secure across all areas of Acquia DAM. This consistency will be carried out through our public API as well.

What’s changing

This change affects the permissions associated with generating download links:

API users must have permission to view the Original Format conversion
For active assets (released and not expired), API users must have permission to Order Active Assets
For expired assets, API users must have permission to Order Expired Assets
For unreleased assets, API users must have permission to Order Unreleased Assets

All permissions referenced above must be applied to at least one asset group in which assets are assigned. Note that no changes will be made to returned files or formats.

The shape of returned download link values will also be changing. For example, previously when retrieving an asset by ID:

curl --request GET \
     --url 'https://api.widencollective.com/v2/assets/{id}' \
     --header 'authorization: Bearer demo/abc123def456'

This would produce the following asset response:

{
  "id": "03a3fcb8-8a03-4974-8c1e-f2ac6c0b3ccd",
  "external_id": "qhvtfxvcdd",
  "filename": "IMG_1815",
  ...
  "_links": {
    "download": "https://embed.widencdn.net/download/api/cloud/qhvtfxvcdd/IMG_1815?signature=1234&expires=5678&use_preferred_extension=true"
  }
}

The change will produce the following response:

{
  "id": "03a3fcb8-8a03-4974-8c1e-f2ac6c0b3ccd",
  "external_id": "qhvtfxvcdd",
  "filename": "IMG_1815",
  ...
  "_links": {
    "download": "https://orders-bb.us-east-1.widencdn.net/download-deferred/originals?asset_wrn=widen%3Aassets%3Aasset%3AMOLCI%3Ag2vtkwnfgd&actor=wrn%3Ausers%3Auser%3A38098962%3A1yrqjp&custom_metadata=(custom_metadata)&Expires=1613718000&Signature=(signature)&Key-Pair-Id=(key-pair-id)"
  }
}

Affected resources

Only version 2.0 of the API is affected.

Here are the API endpoints that will be updated:

List by Search Query
- /v2/assets/search
- /v2/assets/search/scroll
Retrieve Asset by ID
- GET /v2/assets/{id}

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 new download links are returned:

x-widen-api-toggle: new-download-links

For example, when retrieving an asset by ID:

curl --request GET \
     --url 'https://api.widencollective.com/v2/assets/{id}' \
     --header 'authorization: Bearer demo/abc123def456' \
     --header 'x-widen-api-toggle: new-download-links'