What is @api Decorator?

In the realm of Salesforce development, we often need to make our Apex code talk to other parts of the system or even external applications. This is where decorators, also known as annotations, come into play. Among these, the @api decorator holds a special place, acting as a key to unlock your Apex methods and properties for broader accessibility.

At its core, the @api decorator in Salesforce Apex is an annotation used to explicitly mark methods or properties within an Apex class, signaling that they are intended to be exposed and accessible from outside that specific Apex class. This exposure is crucial for enabling interactions with various Salesforce components and external systems.

Purpose of the @api Decorator

The @api decorator serves several vital purposes in Apex development:

• Accessibility Control: It clearly defines which parts of your Apex class are meant to be public interfaces. This makes it explicit that these members are available for use by other Apex classes, Visualforce controllers, Lightning components, and external integrations consuming your Salesforce APIs.
• API Exposure: When you design a class intended to serve as a backend for other applications or components, @api tells the Salesforce platform that these specific methods form the public API of your class.
• Enabling Dynamic Apex: It plays a role in allowing for dynamic invocation of methods, where the method to be called might not be known until runtime.

Key Use Cases and Scenarios

The @api decorator is a cornerstone in modern Salesforce development, particularly with the rise of Lightning Web Components. Let’s explore some of its most common applications:

1. Lightning Web Components (LWC) Integration

This is arguably the most significant use case for @api today. Methods and properties decorated with @api in an Apex class are directly callable or accessible from LWCs. This is the primary mechanism by which LWCs fetch data from, or send data to, the Salesforce backend.

public with sharing class AccountService {
    /**
     * Retrieves a list of accounts based on the provided industry.
     * @param industry The industry to filter accounts by.
     * @return A list of Account records.
     */
    @api // This decorator makes the method callable from LWC
    public static List<Account> getAccountsByIndustry(String industry) {
        return [SELECT Id, Name, Industry FROM Account WHERE Industry = :industry LIMIT 10];
    }
}
        

import { LightningElement, wire } from 'lwc';
// Import the Apex method, using the '@salesforce/apex' namespace
import getAccountsByIndustry from '@salesforce/apex/AccountService.getAccountsByIndustry';

export default class AccountList extends LightningElement {
    accounts;
    error;

    // Use the @wire decorator to call the Apex method reactively
    @wire(getAccountsByIndustry, { industry: 'Technology' })
    wiredAccounts({ error, data }) {
        if (data) {
            this.accounts = data;
            this.error = undefined;
        } else if (error) {
            this.error = error;
            this.accounts = undefined;
        }
    }
}
        

2. Visualforce Controllers

While LWCs are the modern standard, @api also facilitates interaction with Visualforce pages. Methods decorated with @api can be invoked from Visualforce pages using the familiar {! } syntax or through Apex action methods.

public with sharing class ContactController {
    /**
     * An API property that can be bound to from Visualforce.
     */
    @api // Exposes this property to Visualforce
    public String accountId { get; set; }

    /**
     * Retrieves contacts related to the bound account.
     * @return A list of Contact records.
     */
    @api // Exposes this method to Visualforce
    public List<Contact> getContacts() {
        if (String.isNotBlank(accountId)) {
            return [SELECT Id, Name, Email FROM Contact WHERE AccountId = :accountId];
        }
        return new List<Contact>(); // Return empty list if no accountId
    }
}
        

<apex:page controller="ContactController">
    <apex:pageBlock title="Contact Search">
        <apex:pageBlockSection columns="2">
            <apex:pageBlockSectionItem>
                <apex:outputLabel value="Account ID:" for="accountIdInput"/>
                <apex:inputText id="accountIdInput" value="{!accountId}"/>
            </apex:pageBlockSectionItem>
        </apex:pageBlockSection>

        <apex:pageBlock title="Contacts">
            <apex:pageBlockTable value="{!contacts}" var="c">
                <apex:column value="{!c.Name}" headerValue="Contact Name"/>
                <apex:column value="{!c.Email}" headerValue="Email"/>
            </apex:pageBlockTable>
        </apex:pageBlock>
    </apex:pageBlock>
</apex:page>
        

3. Reusable Apex Libraries

When developing utility classes or libraries intended for use across multiple projects or by different developers within an organization, @api helps clearly delineate the public interface. This makes it easier for others to understand and utilize your code without needing to delve into its internal workings.

4. External API Integrations

While @api is not the primary mechanism for exposing your *own* Apex code as a public API to external systems (that’s typically handled by Salesforce APIs like REST or SOAP, or integration patterns like Platform Events), it is fundamental for the Apex methods that *interact with* external services. These methods process inbound API calls or act as intermediaries, and @api ensures they are callable within the Salesforce platform’s integration framework.

@api vs. `public` Keyword

This is a common point of confusion. In Apex, methods and properties declared with the public keyword are already accessible outside their class. So, what’s the difference with @api?

The @api decorator provides a more explicit and semantic declaration, particularly for frameworks like Lightning Web Components. For LWCs, @api is essential. It’s the decorator that the LWC framework specifically looks for to understand which Apex members are meant to be exposed to the JavaScript side. A public method without @api might not be directly discoverable or usable by an LWC in the same way.

Think of public as a general accessibility modifier, and @api as a specific directive for integration points, especially for modern UI frameworks.

Using @api on Properties

Beyond methods, @api can also be applied to properties (getters and setters) within an Apex class. This allows these properties to be directly bound to properties in LWCs, enabling data flow between the Apex controller and the component.

public with sharing class UserProfile {
    /**
     * The username of the user, exposed to the LWC.
     */
    @api // This property can be set or read by an LWC
    public String userName { get; set; }

    // ... other methods and properties
}
        

import { LightningElement, api } from 'lwc';

export default class UserProfileDisplay extends LightningElement {
    // This @api property in LWC will receive a value from a bound Apex @api property
    @api userName;

    // You can also use it in the template, or set it imperatively
    // Example: Assume some logic sets this.userName
}
        

Important Considerations

• Access Modifiers: @api is typically used in conjunction with the public access modifier. It doesn’t replace the need for access control; rather, it enhances it for integration purposes. You cannot decorate private or protected members with @api.
• with sharing vs. without sharing: When your @api methods are invoked from LWCs or Visualforce, the with sharing or without sharing keywords on your Apex class are critical. with sharing enforces the running user’s data access permissions, while without sharing bypasses them. Choose wisely based on your security requirements.
• Metadata: The @api decorator is part of Apex’s metadata. When Salesforce compiles your Apex code, it registers these @api annotated members in the metadata catalog, making them discoverable by other Salesforce features and integrations.

In summary, the @api decorator is a powerful tool for controlling visibility and enabling seamless communication between your Apex code and the rest of the Salesforce ecosystem. It’s indispensable for modern Salesforce development, particularly when leveraging the capabilities of Lightning Web Components.

For more in-depth information, you can refer to the official Salesforce documentation:

• Apex Developer Guide: @api Annotation
• Lightning Web Components Developer Guide: Access Apex Data