AI in the Work

Module 6 of 6 in the chapter APIs, Contracts and Data Across the Wire, chapter 3 of the Integration Architect course. Each module stands on its own. Previous: Schemas and Transformation · Next chapter: The Admin’s Integration Toolkit

The question this module answers: How can AI draft a contract from a sample payload, and how do you check what it drafted?

When I teach this, I stop the class and say: I want to show you something absolutely incredible, as an integration architect. I take a sample payload from a service whose company doesn’t publish an OpenAPI file. I paste the payload into an AI and ask for the YAML. It comes back in about a second.

I used to build those files by hand. It took hours and hours and hours. Now I just ask, and the tools keep getting more powerful.

So in this module, we do it again, with Steve Trucking’s delivery. And then we do the part that matters more: we check it.

Two Rules Before You Paste

Before anything goes into an AI, two rules, every time:

Never paste a secret or a token. Not a client secret, not a bearer token, not a password. If the payload you copied has one in it, take it out first.
Never paste real customer data. Use a made-up sample, like our delivery for Corner Hardware. The shape is what the AI needs, not the people.

And check what your own company allows. Many have rules about which AI tools can see which data.

The Prompt

Here’s the prompt, almost word for word what I type in class:

I am calling a REST web service at https://api.steve-trucking.example/v1/deliveries/D-1042 with a GET, and getting the following JSON. Can you give me the OpenAPI YAML file for it?

And then the sample: the delivery from the contract, with its recipient and its list of items.

If the company does publish documentation, give the AI that too, and ask it to merge the documentation with the sample. The documentation knows things one sample can’t: every status, every error.

What Came Back

We ran it on 2026-10-28, with a fresh AI given nothing but that prompt and that sample. Here’s part of what it wrote, unedited:

openapi: 3.0.3
servers:
  - url: https://api.steve-trucking.example/v1
paths:
  /deliveries/{id}:
    get:
      responses:
        '200':
          description: The delivery.
        '404':
          description: No delivery exists with this ID.
components:
  schemas:
    Delivery:
      type: object
      required: [id, status, depot, weightKg, recipient, items]
      properties:
        status:
          type: string
          example: Delivered
        weightKg:
          type: number
          format: double
        deliveredAt:
          type: string
          format: date-time

AI-generated, 2026-10-28, shortened here. The full file is kept with the course’s sources.

That’s genuinely good. It chose OpenAPI 3.0, which is the version Salesforce’s External Services reads: it takes OpenAPI 2.0 and 3.0, not the newer ones (OpenAPI 2.0 and 3.0 Support (opens in a new tab), Salesforce Help, checked 2026-11-01). It wrote a plain server address, with no placeholders in it, which External Services also needs. It got the types right: text, a decimal number, a whole number for the quantity, a date and time. It built the structure: a recipient object, a list of items. It even added a 404.

In a few seconds, it saved most of the typing.

What a Person Has to Check

Now read it the way an architect does, with the five questions from the contract and the rules from Schemas and Transformation. One sample shows what’s there. It can’t show what should be there. So everything the AI couldn’t see, it guessed.

What’s required. It made six fields required, because all six were in the sample. Our contract requires two. We tested its schema against the in-transit delivery from the last module, the one with only an id and a status: its own schema rejects it. Every delivery still on the road would fail.
The allowed values. The status has an example, Delivered, and no list. So a status of Lost in space passes. One sample shows one value; the people who own the data know there are three.
The errors. The 404 has no shape, and there’s no 400, 401 or 500 at all. In the contract, the errors belong in the contract as carefully as the answers.
Signing in. There’s no security in it at all. The real call needs a bearer token, from the first module. A client built from this file wouldn’t know to send one.
The meaning. The weight is in kilograms only because the field’s name says so. Which depot is North? The file can’t say. That’s the transporter dropping atoms, written into a contract.

Click to enlarge

What AI drafted, and what a person checks.

None of that makes the draft bad. It makes it a draft. It can be smarter than you, and it can be far dumber than you. You need to know where you’re going, and you need to recognize good work and bad.

Check It in the Tool

Then put it to the test. Bring the file into your API client: Postman and most others can import an OpenAPI file and build the calls from it. Make the real call, and compare what comes back with what the file says. The AI drafted the contract; the tool shows you what the system actually does. Our address is a name set aside for examples, so you can’t call it, but on a real API this is the step that catches what reading can’t.

And last, the owners agree. A contract is a promise between two sides. AI can draft it, and you can check it, but both owners have to agree to it, and write it down.

Click to enlarge

The human in the loop.

There’s a back and forth here between you and the AI. Ask it to fix what you found: make only the id and status required, add the three statuses, add the errors and the bearer token. It will, in seconds. That’s where it saves real time. But you had to know what to ask for.

More Ways AI Helps

The contract is one stage of an integration. AI can help at every other stage too, and the pattern is always the same: AI drafts, and a person checks.

Requirements. Give AI one line of a requirement, and it will draft the questions to ask: how many, how often, what happens when it fails. It can’t tell you which of those your business cares about. Chapter 6.
The contract. This module. And when a contract already exists, AI can review it against a checklist: does every call have its errors, is every required field marked, is the sign-in described?
The mapping. Give it a sample from each side and it drafts the mapping, field to field (module 5). Middleware does this too: MuleSoft’s tools can generate a DataWeave transformation from sample input and output data (Using DataWeave Expressions and Transformations in Anypoint Code Builder (opens in a new tab), MuleSoft, checked 2026-11-01).
The code. The classes, the callout, the flow. Salesforce’s own coding agent, Agentforce Vibes, works in VS Code and has a plan mode where “No files change until you approve the plan” (Agentforce Vibes Overview (opens in a new tab), Salesforce Developers, checked 2026-11-01). Check what it writes for credentials, limits and errors. Chapter 9, and the App Development course for directing and reviewing code AI writes.
The tests. This is one of the best uses of all. Give AI the contract, and it drafts the good payloads, the bad ones and the missing ones: a required field left out, text where a number goes, a status nobody expected, a token that’s expired. Chapter 13.
Troubleshooting. Paste in an error message, and AI can explain what it most likely means and where to look. But a log is where secrets hide: tokens in headers, customers in payloads. Take them out first.

Click to enlarge

Where AI helps, and what you check.

And a few habits that hold at every stage:

Give it the real sources. The provider’s documentation and the contract, not only a sample. AI does best where the answer is already written down.
Ask it to list what it guessed. Every assumption, every default. Then check the list, not just the output.
Let the tool be the judge. The API client, the test run, the real system. Not the AI’s confidence.
Keep it out of production. Run what AI writes, and the tests it drafts, in a sandbox or a test org, against test addresses, never against live systems or real customers.
Watch what tools capture. Some tools turn real traffic into tests and examples. That traffic carries tokens and customer records, so check what they keep.
Review it like any code. In version control, reviewed by a person, before it goes anywhere.

The tools keep getting more powerful. The check is the part you can’t hand over.

Where This Goes Next

In class, I don’t stop at the spec. I ask the AI for the Apex classes to receive the data, and then for the service that makes the call. It writes them. And when it hard-codes the endpoint, I ask it to use a named credential instead. That’s chapter 9, where Salesforce calls out. And chapter 4 takes this same OpenAPI file into Salesforce, through External Services, with no code at all.

This is the end of the chapter. You can now read a call, read its contract, follow the data across the wire, check its shape and change it into another. That’s most of what’s on the wire, in any integration.

What an Architect Decides Here

Which AI tools the team may use, and with what data: made-up samples only, never secrets or customer data.
That every AI-drafted contract is checked for what one sample can’t show: required fields, allowed values, errors, sign-in and meaning.
For Salesforce, that the contract is OpenAPI 3.0 or 2.0, with a literal server address, for External Services.
That the draft is tested against the real API in a tool before anyone builds on it.
Where AI-written code and tests run: a sandbox or test org, never production.
Who agrees the contract on each side, and where it’s kept.

Explore

MuleSoft, Using DataWeave Expressions and Transformations in Anypoint Code Builder (opens in a new tab), checked 2026-11-01.
Salesforce Developers, Agentforce Vibes Overview (opens in a new tab), checked 2026-11-01.
Salesforce Help, OpenAPI 2.0 and 3.0 Support (opens in a new tab) (External Services), checked 2026-11-01.
OpenAPI Initiative, OpenAPI Specification v3.0.4 (opens in a new tab): the 3.0 line External Services reads.
The next chapter, The Admin’s Integration Toolkit: this contract, in Salesforce, without code.