Handling Attachments

Integrating images, documents, and videos is crucial for feature-rich applications. Liferay’s headless APIs offer flexible methods for attaching binary data, enabling you to efficiently manage entry attachments:

• Base64 Encoding: Transfer metadata and Base64-encoded binary data within structured JSON payloads.
• By URL: Retrieve files from specified URLs, enabling server-to-server transfers and avoiding direct file uploads.

This dual support enables you to handle a variety of file sizes and storage preferences with Liferay APIs, accommodating both embedded and externally hosted files. This article explores the advantages and trade-offs of these approaches.

Some of Liferay’s headless APIs also support multipart HTTP requests, which segment binary data and metadata. However, other attachment methods offer potentially greater extensibility and simplicity.

Base64 Encoding

Base64 encoding is ideal when prioritizing the combination of metadata and binary data into a single request. This method integrates files as strings within the JSON payload. Here’s an example Base64 call attaching an image to a commerce product:

curl -X 'POST' \
  'http://localhost:8081/o/headless-commerce-admin-catalog/v1.0/products/by-externalReferenceCode/8370bacb-f69d-1e60-acb1-b1d14e8c481c/images/by-base64' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-csrf-token: hCqneNWT' \
  -d '{
  "attachment": "Y3VybCBcCgkiaHR0cDovL2xvY2FsaG9zdDo4MDgwL28vaGVhZGxlc3MtZGVsaXZlcnkvdjEuMC9kb2N1bWVudC1mb2xkZXJzLyR7MX0iIFwKCS0tcmVxdWVzdCAiREVMRVRFIiBcCgktLXVzZXIgInRlc3RAbGlmZXJheS5jb206bGVhcm4i",
  "contentType": "text",
  "galleryEnabled": true,
  "neverExpire": true,
  "title": {"en_US": "Base 64 Image"}
}'

This simplified approach is highly portable and can be used across various systems or APIs without additional setup. It's particularly useful for API interactions behind firewalls restricting external HTTP/HTTPS calls. However, consider these challenges when leveraging Base64:

• Larger Payloads: Base64 encoding increases the size of the payload by roughly 33%, which can cause performance issues with larger files.
• Higher Memory and CPU Usage: Both the client and server must handle encoding/decoding large files.

Since the file and metadata are sent together in a single request, Base64 encoding is primarily suitable for smaller files.

By URL Approach

The "By URL" method offers a streamlined approach for integrating files hosted externally. Instead of direct attachments, you provide an HTTP/HTTPS URL. Liferay then fetches the files, stores them within Document and Media, and establishes links to the relevant resources.

Here’s an example call attaching an image to a commerce product by its URL:

curl -X 'POST' \
  'http://localhost:8081/o/headless-commerce-admin-catalog/v1.0/products/by-externalReferenceCode/8370bacb-f69d-1e60-acb1-b1d14e8c481c/images/by-url' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-csrf-token: hCqneNWT' \
  -d '{
  "src" : "https://clarityvisionsolutions.com/documents/33198/0/home-promotion.png",
  "contentType": "text",
  "galleryEnabled": true,
  "neverExpire": true,
  "title": {"en_US": "URL Image"}
}'

Files hosted externally can be integrated into Liferay without direct uploads, using only metadata and the file URL. This approach optimizes performance by reducing payload sizes and leveraging Liferay’s backend for file transfers. However, these challenges are present with URL attachments:

• URL Accessibility Dependencies: Specified URLs must be accessible to Liferay’s backend and can’t require authentication.
• Error Handling: Attachment operations fail if files can’t be retrieved.
• Security Risks: URLs require proper validation to avoid attaching malicious or unauthorized resources.

Choosing the Right Method

It’s essential to carefully consider which approach for handling binary data is best for the files you're including. This often depends on file sizes, network constraints, and performance requirements.

Use Base64 encoding for embedding smaller, simple files directly within JSON payloads. This method ensures that binary data is self-contained, making it easy to manage alongside metadata. As the 33% file size increase after encoding can significantly impact performance for larger file transfers, avoid using this approach in bandwidth-constrained environments.

Use a URL approach when attaching larger files or binary data that’s already hosted on a CDN or cloud server. This method minimizes client-side network overhead and keeps payload sizes small, making it highly efficient for applications with larger uploads or distributed storage architectures. However, ensuring a reliable hosting environment is essential as this approach relies on the availability and accessibility of the specified URL.

Uploading Clarity’s Attachments

Clarity manages a product catalog with high-resolution images for their commerce platform. Frequently exceeding several megabytes, images are hosted on a CDN to ensure fast delivery and scalability. Using the URL approach enables Clarity to efficiently attach product files without transferring large attachments through their application backend. Instead, the API directly retrieves the images from the CDN, streamlining the process and reducing both client-side processing and network overhead.

For Clarity’s smaller logos and icons, they can leverage Base64 Encoding for improved convenience. Embedding these files within API calls ensures simplicity and eliminates the need to manage external hosting for the assets.

Conclusion

Seamlessly transferring files with APIs requires a robust strategy for handling attachments and binary data. Base64 encoding provides a simplified method to transfer metadata and binary data within structured JSON payloads. Attaching by URL enables larger file transfers and minimizes overhead by leveraging external hosting platforms. By considering file size, network conditions, and system architecture, you can choose attachment approaches that best balance performance and simplicity for your application.

Next, you’ll practice adding attachments to commerce products using Liferay’s headless APIs.