AEM APIs

AEM APIs provide abstractions and functionality specific to productized use cases.

For example, AEM’s PageManager and Page APIs provide abstractions for cq:Page nodes in AEM that represent web pages.

While these nodes are available via Sling APIs as Resources, and JCR APIs as Nodes, AEM’s APIs provide abstractions for common use cases. Using the AEM APIs ensures consistent behavior between AEM the product, and customizations and extensions to AEM.

com.adobe.* vs com.day.* APIs

AEM APIs have an intra-package preference, identified by the following Java™ packages, in order of preference:

  1. com.adobe.cq
  2. com.adobe.granite
  3. com.day.cq

The com.adobe.cq package supports product use cases whereas com.adobe.granite supports cross-product platform use-cases, such as workflow or tasks (which are used across products: AEM Assets, Sites, and so on).

The com.day.cq package contains “original” APIs. These APIs address core abstractions and functionalities that existed before and/or around Adobe’s acquisition of Day CQ. These APIs are supported and should be avoided, unless com.adobe.cq or com.adobe.granite packages does NOT provide a (newer) alternative.

New abstractions such as Content Fragments and Experience Fragments are built out in the com.adobe.cq space rather than com.day.cq described below.

Query APIs

AEM supports multiple query languages. The three main languages are JCR-SQL2, XPath, and AEM Query Builder.

The most important concern is maintaining a consistent query language across the code base, to reduce complexity and cost to understand.

All the query languages have effectively the same performance profiles, as Apache Oak trans-piles them to JCR-SQL2 for final query execution, and the conversion time to JCR-SQL2 is negligible compared to the query time itself.

The preferred API is AEM Query Builder, which is the highest level abstraction and provides a robust API for constructing, executing, and retrieving results for queries, and provides the following:

CAUTION
AEM QueryBuilder API leaks a ResourceResolver object. To mitigate this leak, follow this code sample.

Sling APIs

Apache Sling is the RESTful web framework that underpins AEM. Sling provides HTTP request routing, models JCR nodes as resources, provides security context, and much more.

Sling APIs have the added benefit of being built for extension, which means it is often easier and safer to augment behavior of applications built using Sling APIs than the less extensible JCR APIs.

Common uses of Sling APIs

JCR APIs

The JCR (Java™ Content Repository) 2.0 APIs is part of a specification for JCR implementations (in the case of AEM, Apache Jackrabbit Oak). All JCR implementation must conform to and implement these APIs, and thus, is the lowest level API for interacting with AEM’s content.

The JCR itself is a hierarchical/tree-based NoSQL datastore AEM uses as its content repository. The JCR has a vast array of supported APIs, ranging from content CRUD to querying content. Despite this robust API, it is rare they’re preferred over the higher-level AEM and Sling abstractions.

Always prefer the JCR APIs over the Apache Jackrabbit Oak APIs. The JCR APIs are for interacting with a JCR repository, whereas the Oak APIs are for implementing a JCR repository.

Common misconceptions about JCR APIs

While the JCR is AEM’s content repository, its APIs are NOT the preferred method for interacting with the content. Instead prefer the AEM APIs (Page, Assets, Tag, and so on) or Sling Resource APIs as they provide better abstractions.

CAUTION
Broad use of JCR APIs’ Session and Node interfaces in an AEM application is code-smell. Ensure Sling APIs should be used instead.

Common uses of JCR APIs

OSGi APIs

There is little overlap between the OSGi APIs and the higher-level APIs (AEM, Sling, and JCR), and the need to use OSGi APIs is rare and requires a high level of AEM development expertise.

OSGi vs Apache Felix APIs

OSGi defines a specification all OSGi containers must implement and conform to. AEM’s OSGi implementation, Apache Felix, provides several of its own APIs as well.

  • Prefer OSGi APIs (org.osgi) over Apache Felix APIs (org.apache.felix).

Common uses of OSGi APIs

Exceptions to the rule

The following are common exceptions to the rules defined above.

OSGi APIs

When dealing with low-level OSGi abstractions, such as defining or reading in OSGi component properties, the newer abstractions provided by org.osgi are preferred over higher level Sling abstractions. The competing Sling abstractions have not been marked as @Deprecated and suggest the org.osgi alternative.

Also note the OSGi configuration node definition prefer cfg.json over the sling:OsgiConfig format.

AEM Asset APIs

  • Prefer com.day.cq.dam.api over com.adobe.granite.asset.api.

    • While the com.day.cq Assets API’s provide more complimentary tooling to AEM’s asset management use-cases.
    • The Granite Assets APIs support low-level asset management use-cases (version, relations).