APIs, Contracts and Data Across the Wire

Chapter 3 of Integration Architect, Part 1: Understanding Integration (See). Previous: The Client and Server · Next: The Admin’s Integration Toolkit.

In chapter 2, you made a call and read its answer. This chapter opens the call up. What’s inside a request? Who decides what it should look like? And how does the data itself, a delivery, a customer, an order, leave one system and arrive in another as something that system can use?

That’s what travels on every arrow. Once you can read it, you can read any integration.

The ideas in this chapter

• REST is how most systems talk today. It won because it rides the web: the ports that stayed open, the verbs browsers already used, and data instead of web pages.
• Every call has a verb and three places to put things: the address, the headers and the body. Post is new, patch is a little piece, put is the whole thing. And the answer starts with a status: the 400s are the client’s to fix, the 500s the server’s.
• The server defines the contract, and a good contract covers the errors as carefully as the answers. An OpenAPI file answers five questions, and reading one is easy. A version is a promise, until it retires.
• Serialization is the Star Trek transporter. The object can’t cross the process boundary; its data can, as a stream both sides know how to read, rebuilt on the other side in any language and any shape. And the trip can quietly drop the time zone, the precision, the currency or the characters.
• Every format makes a trade. Fixed-length is fast and can’t change; XML grows but repeats itself; JSON is the usual choice; CSV is small and flat; YAML is for people; binary is the smallest, because it stores values, not characters.
• A schema holds what should be there. A payload only shows what’s there. A schema catches the wrong shape, but not the right shape with the wrong meaning. A mapping turns one system’s shape into another’s, and someone has to own it.
• AI drafts; a person checks. AI writes a contract from one sample in seconds and gets the shape right. It can’t know what one sample doesn’t show. It still needs the human in the loop.

The path through this chapter

Six modules, each standing on its own.

1. The REST Request, Taken Apart. What REST is and how it won; the verbs; the address in two halves; the headers; the body; the status, by the hundred; and why a 200 isn’t data quality.
2. The Contract. What a contract is; the WSDL before REST; the OpenAPI file in five questions; what’s in the box; and a version as a promise.
3. The Star Trek Transporter. Why the transporter was invented; across the process boundary; any language, any shape; four trips on one round trip; and what the transporter can drop.
4. Formats, Old to New. One delivery in every format, measured; why JSON won; and why binary still rules.
5. Schemas and Transformation. What a schema catches and can’t; two shapes, one delivery; and where the mapping lives.
6. AI in the Work. A contract drafted by AI from one sample, checked; the human in the loop; and where else AI helps.

Each idea here is a seed. Chapter 4 takes the contract into Salesforce with no code. Chapter 8 is every door into Salesforce, and chapter 9 is Salesforce calling out. Bulk loads are chapter 10, events chapter 11, signing in chapter 12, and testing and recovery chapter 13.

When you’ve finished, check yourself with the chapter study guide: a checklist for the exam, the habits beyond it, the words to know, and a few questions.

What an architect decides here

• For every call, the verb, the format each way, and what goes in the address, the headers and the body, and never a secret in an address.
• Where the contract lives and who owns it, with the errors in it, and which version each integration is built on.
• How times, numbers, money and characters are sent, so the transporter doesn’t drop them.
• Where the schema is checked, and where the mapping lives, on your side, in the middle, or on theirs, with an owner for each.
• How AI is used: made-up samples only, every draft checked, and nothing it writes run in production untested.

Beyond the exam: AI can now write most of what this chapter describes: the request, the contract, the mapping, the tests. That makes reading them more important, not less. Each module ends with what AI changes, and module 6 is AI at work on a real payload.

Explore

• IETF, HTTP Semantics (RFC 9110) (opens in a new tab): the methods, headers and status codes.
• OpenAPI Initiative, OpenAPI Specification v3.2.0 (opens in a new tab), and Salesforce Help, OpenAPI 2.0 and 3.0 Support (opens in a new tab) (External Services).
• SteveTechArc, Salesforce Documents by Release: each release, its API version, and the guides that came with it.

Next: The Admin’s Integration Toolkit