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.
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 asStringunless you are sure of the format, then convert withDate.valueOforDateTime.valueOfGmt. - Whole numbers become
Integerwhen they fit in 32 bits andLongwhen they do not. Record counters and timestamps in milliseconds often needLong. - Numbers with a decimal point become
Decimal. Use it for money;Doubleinvites rounding surprises. trueandfalsebecomeBoolean.- A
nullin the sample tells you nothing about the type. Look at the API documentation and replace the generatedObjectwith 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:
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.
@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.