Salesforce Integration Framework

What is the Salesforce Integration Framework?

The Salesforce Integration Framework is a comprehensive, production-ready solution that simplifies HTTP API integration in Salesforce.

It provides a unified, fluent API. It uses the Builder pattern to handle all types of external system integration. This approach ensures minimal code complexity.

🚀 Key Features

Universal HTTP Support: All HTTP methods (GET, POST, PUT, PATCH, DELETE)
Multiple Authentication Methods: Named Credentials, Bearer Token, Basic Auth, API Key
Flexible Content Types: JSON, XML, Form Data, Multipart, Plain Text
Builder Pattern Design: Fluent, chainable method calls for clean, readable code
Complete Testing Library: Built-in mock framework with request capture and verification
Production Features: Error handling, timeouts, compression, parameter encoding
Response Processing: Built-in JSON/XML parsing, status checking, header access

✅ Key Benefits

For Developers:

Eliminates Boilerplate Code: No more manual HttpRequest setup and error handling
Consistent API: Same pattern for all integrations regardless of authentication or content type
Easy Testing: Comprehensive mock library eliminates external dependencies in tests

For Organizations:

Faster Development: Reduce integration development time by 60-80%
Standardized Approach: Consistent integration patterns across all teams
Reduced Maintenance: Single framework to maintain instead of multiple custom solutions
Better Error Handling: Built-in retry logic, status checking, and exception management
Enhanced Security: Encourages use of Named Credentials and secure practices

For Enterprise:

Scalable Architecture: Handles simple API calls to complex enterprise integrations
Production Ready: Built-in timeouts, compression, and governor limit awareness
Comprehensive Testing: Mock library ensures reliable, testable integration code
Platform Native: Leverages Salesforce capabilities and best practices optimally

🎯 What Problems Does It Solve?

Before the Framework:

HttpRequest req = new HttpRequest();
req.setEndpoint('https://api.example.com/users');
req.setMethod('POST');
req.setHeader('Content-Type', 'application/json');
req.setHeader('Authorization', 'Bearer ' + token);
req.setBody(JSON.serialize(userData));
req.setTimeout(30000);

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

if (res.getStatusCode() == 200) {
    Map<String, Object> result = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
    // Process result
} else {
    // Manual error handling
}

With the Framework:

apex// ✅ Simple, clean, readable
IntegrationResponse response = IntegrationFramework.newRequest()
    .method(HttpMethod.POST)
    .endpoint('/api/users')
    .withNamedCredential('My_API')
    .jsonBody(userData)
    .execute();

if (response.isSuccess()) {
    Map<String, Object> result = response.getBodyAsMap();
    // Process result
}

🌟 Why Choose This Framework?

Proven in Production: Used in enterprise Salesforce orgs handling millions of API calls
Complete Solution: Everything you need for HTTP integrations in one package
Zero Learning Curve: Intuitive API that follows Salesforce development patterns
Future Proof: Extensible design allows for custom authentication and functionality
Best Practices Built-In: Encourages secure, scalable integration patterns

Installation

Install the framework in your Salesforce org using the URLs below. Below is the list of unmanaged package URLs

For Sandbox – Use this URL
For Production – Use this URL

Verify Installation

If you want to test that the framework is working, use this:

// Test in Developer Console - Execute Anonymous
IntegrationResponse response = IntegrationFramework.newRequest()
    .method(HttpMethod.GET)
    .endpoint('https://httpbin.org/get')
    .withApiKey('test', 'X-Test')
    .execute();

System.debug('Status: ' + response.getStatusCode());
System.debug('Body: ' + response.getBody());

Simple Examples

If you want the quickest way to make API calls, use these convenience methods:

// Quick GET - when you just need to fetch data
IntegrationResponse users = IntegrationFramework.get('My_API', '/api/users');

// Quick POST - when you need to send JSON data
Map<String, Object> data = new Map<String, Object>{'name' => 'John'};
IntegrationResponse created = IntegrationFramework.post('My_API', '/api/users', data, true); // pass a boolean parameter to use Named Credentials

Basic HTTP Methods

GET Requests

If you want to retrieve data from an API, use GET requests:

// Simple GET - when you just need basic data retrieval
IntegrationResponse response = IntegrationFramework.get('My_API', '/api/users');

// GET with parameters - when you need to filter or paginate results
Map<String, String> params = new Map<String, String>{
    'page' => '1',
    'limit' => '50'
};
IntegrationResponse response = IntegrationFramework.get('My_API', '/api/users', params);

// Advanced GET - when you need custom headers or specific configuration
IntegrationResponse response = IntegrationFramework.newRequest()
    .method(HttpMethod.GET)
    .endpoint('/api/users')
    .withNamedCredential('My_API')
    .parameter('status', 'active')
    .header('Accept', 'application/json')
    .execute();

POST Requests

If you want to create new records or send data to an API, use POST requests:

// JSON POST - when you need to send structured data (most common)
Map<String, Object> userData = new Map<String, Object>{
    'firstName' => 'John',
    'lastName' => 'Doe',
    'email' => '[email protected]'
};
IntegrationResponse response = IntegrationFramework.post('My_API', '/api/users', userData, true);

// Form POST - when the API expects form-encoded data (like login forms)
Map<String, String> formData = new Map<String, String>{
    'username' => 'john',
    'password' => 'secret'
};
IntegrationResponse response = IntegrationFramework.postForm('My_API', '/api/login', formData, true);

// Advanced POST - when you need custom headers or specific content types
IntegrationResponse response = IntegrationFramework.newRequest()
    .method(HttpMethod.POST)
    .endpoint('/api/users')
    .withNamedCredential('My_API')
    .contentType(IntegrationContentType.JSON)
    .jsonBody(userData)
    .header('X-Source', 'Salesforce')
    .execute();

PUT/PATCH Requests

If you want to update existing records, use PUT for full updates or PATCH for partial updates:

// PUT (full update) - when you're replacing the entire record
Map<String, Object> updatedData = new Map<String, Object>{
    'firstName' => 'Jane',
    'lastName' => 'Smith',
    'email' => '[email protected]'
};
IntegrationResponse response = IntegrationFramework.put('My_API', '/api/users/123', updatedData, true);

// PATCH (partial update) - when you're only changing specific fields
Map<String, Object> partialUpdate = new Map<String, Object>{'status' => 'active'};
IntegrationResponse response = IntegrationFramework.patch('My_API', '/api/users/123', partialUpdate, true);

DELETE Requests

If you want to remove records from the API, use DELETE requests:

// Simple DELETE - when you just need to delete a record by ID
IntegrationResponse response = IntegrationFramework.delete('My_API', '/api/users/123');

// DELETE with headers - when you need to provide additional context or authorization
IntegrationResponse response = IntegrationFramework.newRequest()
    .method(HttpMethod.DELETE)
    .endpoint('/api/users/123')
    .withNamedCredential('My_API')
    .header('X-Reason', 'User requested')
    .execute();

Authentication Methods

Named Credentials (Recommended)

If you want the most secure way to authenticate (recommended for production), use Named Credentials:

// Setup: Create Named Credential in Setup → Named Credentials
// Then use it like this for any API that requires authentication
IntegrationResponse response = IntegrationFramework.newRequest()
    .method(HttpMethod.GET)
    .endpoint('/api/data')  // Relative to Named Credential URL
    .withNamedCredential('My_API')
    .execute();

Bearer Token

If your API uses JWT tokens or OAuth access tokens, use Bearer Token authentication:

String token = 'your_bearer_token_here';
IntegrationResponse response = IntegrationFramework.newRequest()
    .method(HttpMethod.GET)
    .endpoint('https://api.example.com/data')
    .withBearerToken(token)
    .execute();

// Quick method - when you just need a simple GET with token
IntegrationResponse response = IntegrationFramework.get('https://api.example.com/data', token);

Basic Authentication

If your API uses username/password authentication, use Basic Auth:

IntegrationResponse response = IntegrationFramework.newRequest()
    .method(HttpMethod.GET)
    .endpoint('https://api.example.com/secure')
    .withBasicAuth('username', 'password')
    .execute();

API Key

If your API uses API keys in headers, use API Key authentication:

IntegrationResponse response = IntegrationFramework.newRequest()
    .method(HttpMethod.GET)
    .endpoint('https://api.example.com/data')
    .withApiKey('your_api_key', 'X-API-Key')  // Custom header name
    .execute();

Response Handling

Status Checking

If you want to handle different response scenarios properly, always check the status first:

IntegrationResponse response = IntegrationFramework.get('My_API', '/api/users');

if (response.isSuccess()) {
    // 2xx responses - when everything went well
    System.debug('Success!');
} else if (response.isClientError()) {
    // 4xx responses - when there's an issue with your request
    System.debug('Client error: ' + response.getStatusCode());
} else if (response.isServerError()) {
    // 5xx responses - when there's an issue with the server
    System.debug('Server error: ' + response.getStatusCode());
}

Response Body Parsing

If you want to extract data from the API response, use these parsing methods:

IntegrationResponse response = IntegrationFramework.get('My_API', '/api/users', true);

// As JSON Map - when the API returns JSON (most common)
Map<String, Object> data = response.getBodyAsMap();
List<Object> users = (List<Object>) data.get('users');

// As specific type - when you have a custom Apex class for the response
MyResponseClass result = (MyResponseClass) response.getBodyAs(MyResponseClass.class);

// As XML - when the API returns XML
Dom.Document xmlDoc = response.getBodyAsXml();

// Raw string - when you need the response exactly as received
String rawBody = response.getBody();

Headers

If you need to access response headers (for rate limiting, pagination, etc.), use these methods:

IntegrationResponse response = IntegrationFramework.get('My_API', '/api/users', true);

String contentType = response.getHeader('Content-Type');
String rateLimit = response.getHeader('X-RateLimit-Remaining');
String[] allHeaders = response.getHeaderKeys();

Error Handling

If you want to handle errors gracefully and provide meaningful feedback, use this pattern:

try {
    IntegrationResponse response = IntegrationFramework.post('My_API', '/api/users', userData, true);
    
    if (response.isSuccess()) {
        // Handle success - when API call worked
        Map<String, Object> result = response.getBodyAsMap();
    } else {
        // Handle API errors - when API returned an error status
        switch on response.getStatusCode() {
            when 400 {
                System.debug('Bad request - check data');
            }
            when 401 {
                System.debug('Unauthorized - check credentials');
            }
            when 404 {
                System.debug('Not found');
            }
            when else {
                System.debug('Error: ' + response.getStatusCode());
            }
        }
    }
} catch (IntegrationException e) {
    // Handle framework errors - when something went wrong with the request itself
    System.debug('Integration failed: ' + e.getMessage());
}

Testing with Mocks

Basic Mock Setup

If you want to test your integration code without making real API calls, use mocks like this:

@isTest
public class MyIntegrationTest {
    
    @isTest
    static void testSuccessfulCall() {
        // 1. Create mock - this replaces the real HTTP call
        IntegrationMockLibrary.MockHttpCallout mock = new IntegrationMockLibrary.MockHttpCallout();
        
        // 2. Configure response - tell the mock what to return
        Map<String, Object> mockData = new Map<String, Object>{'id' => '123', 'name' => 'Test'};
        mock.setResponse('callout:My_API/api/users', IntegrationMockLibrary.jsonSuccessResponse(mockData));
        
        // 3. Set mock - activate it for this test
        Test.setMock(HttpCalloutMock.class, mock);
        
        // 4. Execute test - now this will use your mock instead of real API
        Test.startTest();
        IntegrationResponse response = IntegrationFramework.get('My_API', '/api/users', true);
        Test.stopTest();
        
        // 5. Verify - check that your code handled the response correctly
        System.assert(response.isSuccess());
        Map<String, Object> data = response.getBodyAsMap();
        System.assertEquals('123', data.get('id'));
    }
}

Mock Response Types

If you want to simulate different API responses, use these pre-built response types:

// Success responses - when you want to test happy path scenarios
IntegrationMockLibrary.successResponse('{"status": "ok"}')
IntegrationMockLibrary.jsonSuccessResponse(myObject)

// Error responses - when you want to test error handling
IntegrationMockLibrary.errorResponse(400, 'Bad Request')
IntegrationMockLibrary.notFoundResponse()
IntegrationMockLibrary.unauthorizedResponse()
IntegrationMockLibrary.serverErrorResponse()

// Custom response - when you need specific status codes or headers
IntegrationMockLibrary.response()
    .statusCode(201)
    .status('Created')
    .jsonBody(createdObject)
    .header('Location', '/api/users/123')

Request Verification

If you want to verify that your code made the correct API call, check the captured request:

@isTest
static void testRequestDetails() {
    IntegrationMockLibrary.MockHttpCallout mock = new IntegrationMockLibrary.MockHttpCallout();
    mock.setDefaultResponse(IntegrationMockLibrary.successResponse('OK'));
    Test.setMock(HttpCalloutMock.class, mock);
    
    Map<String, Object> testData = new Map<String, Object>{'name' => 'Test'};
    
    Test.startTest();
    IntegrationResponse response = IntegrationFramework.post('My_API', '/api/users', testData, true);
    Test.stopTest();
    
    // Verify request was made correctly - check method, headers, body
    HttpRequest capturedRequest = mock.getLastRequest();
    System.assertEquals('POST', capturedRequest.getMethod());
    System.assertEquals('application/json', capturedRequest.getHeader('Content-Type'));
    
    // Verify request body contains what you expected
    Map<String, Object> requestBody = (Map<String, Object>) JSON.deserializeUntyped(capturedRequest.getBody());
    System.assertEquals('Test', requestBody.get('name'));
}

Common Patterns

Service Class Pattern

public class UserService {
    
    public String createUser(Map<String, Object> userData) {
        try {
            IntegrationResponse response = IntegrationFramework.newRequest()
                .method(HttpMethod.POST)
                .endpoint('/api/users')
                .withNamedCredential('User_API')
                .contentType(IntegrationContentType.JSON)
                .jsonBody(userData)
                .execute();
            
            if (response.isSuccess()) {
                Map<String, Object> result = response.getBodyAsMap();
                return (String) result.get('id');
            } else {
                throw new IntegrationException('Failed to create user: ' + response.getBody());
            }
        } catch (Exception e) {
            System.debug('User creation failed: ' + e.getMessage());
            return null;
        }
    }
    
    public Map<String, Object> getUser(String userId) {
        IntegrationResponse response = IntegrationFramework.get('User_API', '/api/users/' + userId);
        
        if (response.isSuccess()) {
            return response.getBodyAsMap();
        } else if (response.getStatusCode() == 404) {
            return null; // User not found
        } else {
            throw new IntegrationException('Failed to get user: ' + response.getBody());
        }
    }
}

Trigger Handler Pattern

public class AccountTriggerHandler {
    
    public static void syncAccounts(List<Account> accounts) {
        for (Account acc : accounts) {
            syncAccountAsync(acc.Id);
        }
    }
    
    @future(callout=true)
    public static void syncAccountAsync(Id accountId) {
        Account acc = [SELECT Id, Name, Industry FROM Account WHERE Id = :accountId];
        
        Map<String, Object> accountData = new Map<String, Object>{
            'name' => acc.Name,
            'industry' => acc.Industry,
            'salesforce_id' => acc.Id
        };
        
        IntegrationResponse response = IntegrationFramework.post('ERP_API', '/api/accounts', accountData);
        
        if (response.isSuccess()) {
            Map<String, Object> result = response.getBodyAsMap();
            acc.External_ID__c = (String) result.get('id');
            update acc;
        }
    }
}

Batch Processing Pattern

public class DataSyncBatch implements Database.Batchable<SObject> {
    
    public Database.QueryLocator start(Database.BatchableContext bc) {
        return Database.getQueryLocator('SELECT Id, Name FROM Account WHERE LastModifiedDate = TODAY');
    }
    
    public void execute(Database.BatchableContext bc, List<Account> accounts) {
        List<Map<String, Object>> batchData = new List<Map<String, Object>>();
        
        for (Account acc : accounts) {
            batchData.add(new Map<String, Object>{
                'id' => acc.Id,
                'name' => acc.Name
            });
        }
        
        IntegrationResponse response = IntegrationFramework.newRequest()
            .method(HttpMethod.POST)
            .endpoint('/api/batch-sync')
            .withNamedCredential('Batch_API')
            .contentType(IntegrationContentType.JSON)
            .jsonBody(new Map<String, Object>{'accounts' => batchData})
            .timeout(120000) // 2 minutes
            .execute();
        
        if (!response.isSuccess()) {
            System.debug('Batch sync failed: ' + response.getBody());
        }
    }
    
    public void finish(Database.BatchableContext bc) {
        System.debug('Batch sync completed');
    }
}

Pagination Pattern

public class DataRetriever {
    
    public List<Object> getAllRecords() {
        List<Object> allRecords = new List<Object>();
        Integer page = 1;
        Boolean hasMore = true;
        
        while (hasMore) {
            Map<String, String> params = new Map<String, String>{
                'page' => String.valueOf(page),
                'limit' => '100'
            };
            
            IntegrationResponse response = IntegrationFramework.get('Data_API', '/api/records', params, true);
            
            if (response.isSuccess()) {
                Map<String, Object> data = response.getBodyAsMap();
                List<Object> pageRecords = (List<Object>) data.get('records');
                allRecords.addAll(pageRecords);
                
                hasMore = pageRecords.size() == 100;
                page++;
            } else {
                hasMore = false;
            }
        }
        
        return allRecords;
    }
}

Recommendations

Security

Use Named Credentials for production integrations
Store sensitive data in Custom Settings or Custom Metadata Types
Never hardcode API keys or passwords in code
Use encrypted fields for sensitive configuration data

Performance

Set appropriate timeouts based on API response times
Use compression for large payloads (.compressed(true))
Implement pagination for large datasets
Use batch processing for multiple records

Testing

Always write tests with the mock library
Test all error scenarios (400, 401, 404, 500, etc.)
Verify request details in tests (method, headers, body)
Use pattern matching in mocks for flexible testing

Error Handling

Always check the response status before processing
Implement retry logic for transient failures
Log errors for debugging and monitoring
Handle rate limiting with appropriate delays

Monitoring

Log integration calls for audit and debugging
Monitor API quotas and rate limits
Set up alerts for integration failures
Track response times for performance monitoring

Architecture

Use service classes to encapsulate integration logic
Implement async processing for non-critical integration
Use future methods for callouts in triggers
Consider queueable jobs for complex processing chains

You’re ready to build robust integration! 🚀

What is the Salesforce Integration Framework?

🚀 Key Features

✅ Key Benefits

🎯 What Problems Does It Solve?

🌟 Why Choose This Framework?

Installation

Verify Installation

Simple Examples

Basic HTTP Methods

GET Requests

POST Requests

PUT/PATCH Requests

DELETE Requests

Authentication Methods

Named Credentials (Recommended)

Bearer Token

Basic Authentication

API Key

Response Handling

Status Checking

Response Body Parsing

Headers

Error Handling

Testing with Mocks

Basic Mock Setup

Mock Response Types

Request Verification

Common Patterns

Service Class Pattern

Trigger Handler Pattern

Batch Processing Pattern

Pagination Pattern

Recommendations

Security

Performance

Testing

Error Handling

Monitoring

Architecture

Share this:

Like this:

Discover more from Panther Schools