We are pleased to share version 1.7 of our Java API, which introduces improvements to our search functionality and the Albums features. This release enhances security, simplifies configuration, and modernises core architecture. If your integration uses the search functionality or album management endpoints detailed below, updates to your integration code may be required. We strongly recommend testing your integration on your staging environment before the production release.
Potentially Breaking Changes
Search Functionality
Changes to the search and simpleSearch endpoint response structure:
- Updated hits.total field from integer to object containing value and relation
- The _type field will now consistently return "_doc". Please ensure your integration uses the existing assetType field within _source for resource type information
Resource Type Differentiation
Rather significant reminder that resource types should be identified using: -
- Required approach: Use assetType field within _source
- Deprecated approach: Using _type field (will now always return "_doc")
- Important note: assetType provides proper classification (e.g., "image", "video", "folder")
Implementation Guidance
// Previous approach (will no longer work) const isFolder = hit._type === "folder"; // New approach const isFolder = hit._source.assetType === "folder"; const isAsset = hit._source.assetType !== "folder"; // For specific asset types const isImage = hit._source.assetType === "image"; const isVideo = hit._source.assetType === "video";
Album Management
- Album IDs: Now using UUID4 format
- addAlbumAssets: Automatically includes permitted transforms
- getAlbumAssets: Returns transform lists per asset
- Removed endpoints: createAlbumShortLink, getAlbumGlobalTransforms, getAlbumSentEntry
New Endpoints
- getAlbumAssetDownloadOptions
- getAssetDownloadOptions
- updateAlbumAssetDownloadOptions
Core Improvements
- Unified Album System: Consolidated sharing mechanisms
- Enhanced Security: Dynamic, category-level permissions
- Persistent Share Links: Single, permanent link per album
- Legacy Support: Existing valid share links remain functional
- Modern Architecture: Improved system stability and performance
Integration Verification
Timeline
- Staging environment available: 20th December 2024
- Recommended testing completion: 12th January 2025
- Production release: 18th January 2025
Testing Checklist
Review if your integration uses:
- Search result parsing, particularly:
- Verify correct use of _source.assetType for type identification
- Total results handling
- Resource type filtering
- Album ID handling
- Transform management
- Legacy album access
Migration Path
We've prioritised backwards compatibility where possible:
- Existing album share links remain functional
- Legacy albums have been migrated automatically
- Search functionality maintains core data structure within _source
FAQ
How do I know if these changes affect my integration?
Test your integration on your staging environment. Focus particularly on search functionality and album management if you use these features.
What specifically breaks in the search response?
Only integrations that directly reference the hits.total structure or incorrectly use the _type field need updating. Correctly implemented integrations using _source.assetType for resource type identification remain stable.
Do all album integrations require updates?
Only if you use album IDs or the removed endpoints. Existing share links remain functional.
How should we handle the new asset type differentiation?
Transition from using _type to _source.assetType for type checking. The new approach provides more granular classification whilst maintaining backwards compatibility through the folder/non-folder distinction.
What happens to existing album shares?
All existing share links remain functional. New albums receive a permanent short link, whilst legacy albums maintain their existing access points.
Important Note on Version Handling
API version handling should follow Step 1 in the Authentication section of our API documentation. Whilst most integrations already implement dynamic version handling, any hardcoded version numbers should be updated before the 18th January 2025 release to ensure continued functionality.
Support and Resources
Our team stands ready to assist with your testing and implementation:
- Technical guidance is available via [email protected]
- Documentation: API Documentation
- Staging environment access: Contact your account manager
We're quite keen to ensure a smooth transition for all our clients. Please don't hesitate to reach out should you need any assistance.