Skip to content

How to turn a JSON response into Apex wrapper classes

A practical guide to deserializing JSON in Apex: wrapper classes, type choices, reserved words, null values and how to test your parser.

6 minute readUpdated By Kappa Vinay

Almost every Salesforce integration ends the same way: an HTTP callout returns a JSON string, and Apex needs to read values out of it. You can walk the payload with JSON.deserializeUntyped and a chain of casts, but typed wrapper classes are easier to read, easier to test and fail earlier when the payload changes.

What a wrapper class is

A wrapper class is a plain Apex class whose properties mirror the keys of a JSON object. JSON.deserialize creates an instance and fills each property whose name matches a key.

Apex
public class OrderResponse {
    public String orderId;
    public Decimal total;
    public List<Line> lines;

    public class Line {
        public String sku;
        public Integer quantity;
    }
}

OrderResponse res = (OrderResponse) JSON.deserialize(body, OrderResponse.class);

Nested objects become inner classes and arrays become List<T>. Apex allows only one level of inner classes, so every generated class sits directly inside the root class, however deep the JSON goes.

Choosing the right types

  • Text becomes String. Dates usually arrive as text too; keep them as String unless you are sure of the format, then convert with Date.valueOf or DateTime.valueOfGmt.
  • Whole numbers become Integer when they fit in 32 bits and Long when they do not. Record counters and timestamps in milliseconds often need Long.
  • Numbers with a decimal point become Decimal. Use it for money; Double invites rounding surprises.
  • true and false become Boolean.
  • A null in the sample tells you nothing about the type. Look at the API documentation and replace the generated Object with the real type.

Keys that are not valid Apex names

JSON keys can be anything. Apex identifiers cannot: they must start with a letter, may not contain hyphens or double underscores, and may not be reserved words such as class, limit, date or new.

Because JSON.deserialize matches by name, a property called class_x will never receive the value of a key called class. The usual fix is to rename the key in the JSON text just before deserializing:

Apex
jsonString = jsonString.replaceAll('"class"\\s*:', '"class_x":');

The pattern only matches a quoted name followed by a colon, which is how keys appear in JSON, so string values that happen to contain the same word are left alone.

Extra and missing keys

By default, JSON.deserialize ignores keys that have no matching property and leaves properties without a matching key as null. That is forgiving, and usually what you want for third-party APIs that add fields over time. If you need the opposite, JSON.deserializeStrict throws when the payload contains a key your class does not declare.

Test the parser with a real payload

Save a representative response as a string in your test class, parse it, and assert on a few values from different depths. A test like this fails loudly when someone renames a property.

Apex
@IsTest
static void parsesOrderResponse() {
    String body = '{"orderId":"A-1","total":19.5,"lines":[{"sku":"X","quantity":2}]}';
    OrderResponse res = OrderResponse.parse(body);
    Assert.areEqual('A-1', res.orderId);
    Assert.areEqual(2, res.lines[0].quantity);
}

A generator infers types from the one sample you give it. If a field is sometimes a number and sometimes text, or an array is empty in your sample, check the API documentation before you deploy.