Apex Integration Best Practices: Building Robust Salesforce Integrations

Integrating Salesforce with external systems can be a game-changer for streamlining business processes, ensuring data consistency, and extending your org’s capabilities. However, such integrations also raise concerns about performance, security, and reliability. By following certain best practices in Apex integration, you ensure your solution remains robust and scalable.

1. Use Named Credentials for Secure Callouts

Why: Instead of storing credentials or tokens in Apex code, you can define an endpoint and authentication (e.g., OAuth 2.0, Basic Auth) in Named Credentials. Apex then references it with a simple callout: prefix, keeping your code environment-agnostic and avoiding hardcoded secrets.

public class NamedCredentialService {
    public static String callExternalService() {
        HttpRequest req = new HttpRequest();
        req.setEndpoint('callout:My_External_Service/resource/path');
        req.setMethod('GET');
        req.setHeader('Content-Type','application/json');

        // Named Credential handles authentication automatically
        Http http = new Http();
        HttpResponse res = http.send(req);
    }
}        

Best Practices:

• Admin-Managed: Let admins update authentication details or endpoints without deploying code.
• Secure: Minimizes credential exposure; also masks them from debug logs.

2. Bulkify and Asynchronize Callouts

Why: Large data volumes or time-intensive external calls can degrade user experience if executed synchronously. Use Queueable, Future methods, or Batch Apex to offload heavier tasks.

public class BulkQueueableCallout implements Queueable, Database.AllowsCallouts {
    private List<Id> recordIds;
    public BulkQueueableCallout(List<Id> recordIds) {
        this.recordIds = recordIds;
    }

    public void execute(QueueableContext context) {
        List<MyObject__c> records = [
            SELECT Id, Name, External_Ref__c
            FROM MyObject__c
            WHERE Id IN :recordIds
        ];

        // Example logic: Call out for each record's External_Ref__c
        for (MyObject__c rec : records) {
            HttpRequest req = new HttpRequest();
            req.setEndpoint('callout:My_Named_Credential/resource/' + rec.External_Ref__c);
            req.setMethod('GET');
            HttpResponse resp = (new Http()).send(req);
            // Process response or update fields
        }
    }
}        

Best Practices:

• Use Database.AllowsCallouts when making callouts in asynchronous contexts.
• Handle Partial Failures: If one record’s callout fails, you might skip it or log an error, allowing the rest to proceed.

3. Manage Timeouts and Retries

Why: Network hiccups and external service downtimes are inevitable. The default timeout might not always suffice or might be too lenient.

public class TimeoutRetryService {
    public static String doCalloutWithRetry() {
        Integer maxAttempts = 3;
        Integer attempt = 0;
        String finalResponse;

        while (attempt < maxAttempts) {
            attempt++;
            try {
                HttpRequest req = new HttpRequest();
                req.setEndpoint('callout:ExternalService');
                req.setMethod('POST');
                req.setTimeout(15000); // 15 seconds
                req.setBody('{"data":"test"}');

                Http http = new Http();
                HttpResponse res = http.send(req);

                if (res.getStatusCode() == 200) {
                    finalResponse = res.getBody();
                    break;
                } else {
                    // Could log or throw a custom exception or set custom final response
                }
            } catch (Exception e) {
                // If we're on the final attempt, rethrow
                if (attempt == maxAttempts) {
                    throw e;
                }
            }
        }
        return finalResponse;
    }
}        

Retry Logic:

• Try-Catch: If a callout fails or times out, catch the exception and decide whether to reschedule a retry (e.g., re-queue a job or log it for manual reprocessing).
• Prevent Infinite Loops: Implement a max attempts counter. The logic might store each record’s attempt count in a custom field or keep it in a static variable for one transaction.

4. JSON Parsing and Error Handling

Why: Many REST APIs return JSON. Apex supports JSON.deserialize() robust parsing, but you must handle partial or erroneous payloads gracefully.

public class JsonParserHelper {
    public class ExternalResponse {
        public String status;
        public String message;
        public Decimal amount;
    }

    public static ExternalResponse parseJson(String jsonBody) {
        try {
            ExternalResponse parsed = (ExternalResponse) JSON.deserialize(jsonBody, ExternalResponse.class);
            return parsed;
        } catch (Exception e) {
            System.debug('JSON Parsing Error: ' + e.getMessage());
            return null;
        }
    }

    public static void handleApiResponse(String jsonBody) {
        ExternalResponse res = parseJson(jsonBody);
        if (res == null) {
            // Possibly throw a custom exception or log
        } else if (res.status == 'Error') {
            // Log, rethrow, or handle gracefully
        } else {
            // Proceed with normal logic
        }
    }
}        

Best Practices:

• Check Response Codes: A 200 isn’t the only success status if your external API uses different codes.
• Log Errors: Store the status code, partial body, or error message for troubleshooting.
• Validate Data: If fields are missing or in an unexpected format, handle it to avoid NullPointerExceptions.

5. Handle Security and Compliance

Key Points:

1. HTTPS: Ensure all endpoints use TLS/SSL.
2. Encryption: If storing sensitive data locally, consider using protected custom metadata or encryption solutions.
3. Sharing and FLS: Even if your Apex is in system mode, confirm compliance with your org’s security or regulatory requirements.

6. Performance and Governor Limits

Minimize Round Trips:

• Batch or combine requests if the external API supports it. Fewer total callouts translates into fewer potential failures.

Timeout Management:

• Set an appropriate req.setTimeout(...) match to the external system’s average response time.

Avoid Over-Triggering:

• For record-driven callouts (like after triggers), consider asynchronous invocation. Or group updates if you anticipate multiple triggers for the same record.

Use Queues:

• If you rely on external data to update many records, queue the logic so each chunk is well-defined, avoiding CPU or DML limit spikes.

7. Testing and Mocking

Why: You want reliable, repeatable tests that don’t rely on an actual external service. Approach: Use HttpCalloutMock to return synthetic responses:

@IsTest
private class MyIntegrationTest {
    @IsTest
    static void testCalloutMock() {
        Test.setMock(HttpCalloutMock.class, new MyHttpMock());
        String response = NamedCredentialService.callExternalService();
        System.assertEquals('Mock Response', response, 'Unexpected response body');
    }
}

private class MyHttpMock implements HttpCalloutMock {
    public HttpResponse respond(HttpRequest req) {
        HttpResponse res = new HttpResponse();
        res.setStatusCode(200);
        res.setBody('Mock Response');
        return res;
    }
}        

Mocking:

• Provides consistent JSON or XML responses.
• Permits testing success and error scenarios, raising confidence your code handles everything gracefully.

Conclusion

Apex integration is potent for connecting Salesforce to external APIs but calls for robust design around security, performance, and error handling. By leveraging Named Credentials, asynchronous patterns, retries, and mock testing, you’ll ensure your integration is both resilient and easy to maintain as your org evolves.

Key Takeaways:

1. Secure and Simplify with Named Credentials.
2. Asynchronize heavy or time-consuming callouts (Queueable / Batch Apex).
3. Graceful error handling and logging for debugging.
4. Thorough Testing with HttpCalloutMock.
5. Performance mindsets: combine requests, watch timeouts, manage concurrency.