Advanced 25 min read

Design the Integration Contract

By the end of this lesson, you'll be able to:

Define exactly what an external API call needs to send and expects to receive
Sketch the service method signature before writing any callout code
Recognize why designing the contract first avoids rework once the callout exists

Prerequisites: Module 36: "Integrating Apex with the Outside World"

What we're building

"Given an amount in South African Rand and a target currency code,
call an external exchange rate API and return the converted amount
— reliably, securely, and with proper error handling for when the
external service is slow or unavailable."

This is a genuinely realistic integration: a real HTTP callout, real authentication, real JSON parsing, real failure modes — every lesson from Module 36 gets used here, in one complete feature.

Defining the contract precisely

Request:  GET https://api.example.com/convert?from=ZAR&to={currency}&amount={amount}
Response: {"convertedAmount": 123.45, "rate": 0.054, "timestamp": "2026-08-06T10:00:00Z"}

Stating the exact request shape and exact expected response shape — before writing any Apex — is Module 26's "Design the Requirement" discipline, applied to an external contract this time instead of an internal business rule. Any assumption made here becomes something the JSON-parsing lesson can build against directly, rather than guessing later.

Sketching the service method

CurrencyConversionService
  - convert(Decimal amountInZar, String targetCurrency) : Decimal

One focused method, matching Lesson 1's contract almost exactly — this small, deliberate API surface is what every following lesson in this module builds toward, one piece at a time.

Exercise

As a comment, decide what should happen if the external API returns a currency code the service doesn't recognize, and add it to the contract.

Show hint

Think about whether this is a client-side check or something the API itself would reject.

APEX

Design the Integration Contract Quiz

1. Why define the exact request and response shape before writing any Apex callout code?

So every following lesson can build against a concrete contract instead of guessing what the API expects or returns Apex requires a written API contract to compile It has no real benefit beyond documentation External APIs never actually have a fixed contract

My Notes

Questions about this lesson

No questions yet — be the first to ask.

Summary

This module builds a currency exchange rate integration end to end — starting, as every project has, by defining precisely what the external API expects and returns before writing a single line of callout code.

← Testing Integrations Build the Callout Service →