REST Callouts from Apex with Named Credentials

Salesforce rarely lives alone: orders go to an ERP, payments to a gateway, addresses to a validation service. From Apex you call those REST APIs with HttpRequest – everything from the earlier chapters (methods, status codes, JSON, auth, retries, idempotency) applies. What's specific to Salesforce is how you store credentials safely and how governor limits shape your code.

Credentials: never in code

A Named Credential stores the base URL; its External Credential stores the authentication (OAuth 2.0 client credentials, API key header, Basic, JWT…), and permission sets decide which users may use it. Apex refers to it by name with the callout: prefix – no URLs or secrets in your code, and no Remote Site Settings needed.

A complete callout

public with sharing class PaymentsClient {
    public class RefundRequest {
        public String paymentId;
        public Integer amount;           // minor units, e.g. paise
        public String reason;
    }
    public class RefundResult {
        public String id;
        public String status;
    }
    public class PaymentsException extends Exception {}

    public static RefundResult refund(RefundRequest body, String idempotencyKey) {
        HttpRequest req = new HttpRequest();
        req.setEndpoint('callout:Payments_API/v1/refunds');
        req.setMethod('POST');
        req.setHeader('Content-Type', 'application/json');
        req.setHeader('Idempotency-Key', idempotencyKey);     // safe to retry
        req.setBody(JSON.serialize(body));
        req.setTimeout(20000);                                // milliseconds (max 120,000)

        HttpResponse res = new Http().send(req);
        Integer status = res.getStatusCode();
        if (status == 200 || status == 201) {
            return (RefundResult) JSON.deserialize(res.getBody(), RefundResult.class);
        }
        if (status == 409 || status == 422) {
            throw new PaymentsException('Refund rejected: ' + res.getBody());     // business error – show the user
        }
        throw new PaymentsException('Payments API error ' + status);             // 5xx – retry later
    }
}

• JSON.serialize and JSON.deserialize map Apex classes to JSON; for dynamic shapes use JSON.deserializeUntyped.
• Check the status code yourself – send() doesn't throw for 4xx/5xx, just like fetch.
• Pass an idempotency key (for example the Salesforce record Id plus an attempt marker) when the remote API supports it.

Limits and async callouts

public class RefundJob implements Queueable, Database.AllowsCallouts {
    private final Id caseId;
    public RefundJob(Id caseId) { this.caseId = caseId; }

    public void execute(QueueableContext ctx) {
        Case c = [SELECT Id, Payment_Id__c, Refund_Amount__c FROM Case WHERE Id = :caseId WITH USER_MODE];
        PaymentsClient.RefundRequest body = new PaymentsClient.RefundRequest();
        body.paymentId = c.Payment_Id__c;
        body.amount = c.Refund_Amount__c.intValue();
        body.reason = 'customer_request';
        PaymentsClient.RefundResult result = PaymentsClient.refund(body, 'refund-' + c.Id);
        update as user new Case(Id = c.Id, Refund_Status__c = result.status);   // DML after the callout is fine
    }
}
// from a trigger or handler: System.enqueueJob(new RefundJob(caseId));

Testing with HttpCalloutMock

Apex tests can't make real callouts; you provide a mock that returns a fake response:

@IsTest
private class PaymentsClientTest {
    private class SuccessMock implements HttpCalloutMock {
        public HttpResponse respond(HttpRequest req) {
            Assert.areEqual('POST', req.getMethod());
            Assert.isTrue(req.getEndpoint().endsWith('/v1/refunds'));
            Assert.isNotNull(req.getHeader('Idempotency-Key'));
            HttpResponse res = new HttpResponse();
            res.setStatusCode(201);
            res.setHeader('Content-Type', 'application/json');
            res.setBody('{"id":"rf_1","status":"pending"}');
            return res;
        }
    }

    @IsTest
    static void refundSucceeds() {
        Test.setMock(HttpCalloutMock.class, new SuccessMock());
        PaymentsClient.RefundRequest body = new PaymentsClient.RefundRequest();
        body.paymentId = 'pay_1';
        body.amount = 49900;
        Test.startTest();
        PaymentsClient.RefundResult r = PaymentsClient.refund(body, 'refund-test-1');
        Test.stopTest();
        Assert.areEqual('pending', r.status);
    }
}

New to Apex? Our Salesforce Apex course covers classes, SOQL, DML and testing from the start.

Practice

Summary