My Articles · API Fundamentals
Every integration — REST or SOAP, enterprise CRM or modern AI platform — is built from the same six components. Here's what's actually inside a request and a response, and why each piece matters.
“Endpoint and method tell you what's happening. Headers and auth tell you who's allowed. The body tells you what's actually moving. Every integration problem I've ever debugged traces back to one of those three being wrong.”
Most people describe API integrations in vague terms — “the systems talk to each other,” “data syncs back and forth.” That's true, but it's not an answer a technical buyer or an engineer finds convincing. Underneath every integration, no matter how modern or how legacy, sits the same six-part structure. Once you can see it, you can describe your own work with precision instead of hand-waving.
Part 01An endpoint is a URL representing one resource — a thing, not an action. The action comes from the HTTP method paired with it. This pairing is the core idea behind REST API design, and it's the first thing that separates a well-designed API from a clunky one.
https://api.example.com/v2/leads/44821?fields=email,status
/leads is correct design. /getLeads is a design smell — the verb belongs to the method, not the URL. And APIs get versioned (/v2/) because a platform can't break every existing integration every time it ships a change. Part of real integration work is knowing which version you're built against, and knowing when a platform is about to deprecate it.
| Method | Does | Idempotent |
|---|---|---|
| GET | Read a resource | Yes — calling it 10 times has the same effect as once |
| POST | Create a new resource | No — calling it twice creates two records |
| PUT | Replace the whole record | Yes |
| PATCH | Update part of a record | Usually |
| DELETE | Remove a resource | Yes — deleting twice still leaves it deleted |
“Idempotent” is the one piece of vocabulary here that signals real depth — it means safe to retry without side effects. If a call times out and you don't know whether it landed, you can safely retry a PUT or DELETE. Retry a POST blindly and you might create a duplicate Lead. That's a real, practical reason integrations need dedup logic on the create side — not a textbook detail.
Every API call has two halves. What you send has to be understood by the other system; what comes back has to be understood by you. Here's what's actually inside each one.
The body has to match a schema both sides agree on — this is the field-mapping work at the center of most real integration projects. Today, that packet is almost always JSON: lightweight, human-readable, the default for REST APIs. Older enterprise platforms often still speak XML, wrapped in the heavier SOAP protocol — which is why “REST/SOAP integration” shows up together on a lot of enterprise resumes, mine included. REST+JSON is the modern default. SOAP+XML is the legacy-enterprise pattern — banking, telecom, big ERP systems that haven't modernized. If you're talking to an API-first platform built in the last few years, it's REST, full stop.
Most modern SaaS platforms use OAuth 2.0 rather than a static API key — a token issued after an auth handshake, scoped to specific permissions, that expires and has to be refreshed. This is, in practice, the single most common thing that breaks in a live integration, and the first thing a customer's technical team asks about. A static API key is simpler but cruder — no expiration, no scoping, harder to rotate safely. Knowing which pattern a platform uses, and why, tells you a lot about how mature that platform's integration story actually is.
Is the integration one-way or bidirectional? Real-time per event, or batched and polled on a schedule? This is often the most important question in a discovery conversation, because it determines the whole architecture downstream — and it's the one most people skip until it's too late to change course.
To make the six parts concrete, here's how they map onto a real integration I manage end to end.
“I manage an AppExchange-listed Salesforce integration end to end — a bi-directional REST/SOAP integration syncing Lead, Opportunity, and Case data. On the authorization side, it's OAuth 2.0, so I deal with token scoping and refresh directly when something breaks. The harder part is the data packet itself — mapping our fields to whatever custom object structure a customer's org already has, which means I'm regularly resolving field-level conflicts and configuring field-level security so we're only exposing what should cross that boundary. Separately, on the client side, I read and troubleshoot the JavaScript that fires those API calls directly from a customer's website — so I see both ends: the browser-side call going out, and the server-side sync validating and mapping what comes in.”
An API integration isn't one thing — it's six specific decisions, made twice, once for the request and once for the response. Endpoint and method. Headers and auth. The data packet and its format. Status code. Response body. Direction and timing.
“Built integrations” is a claim anyone can make. Naming the six parts — and being able to point to where your own work actually lives inside them — is what separates real fluency from a vague gesture at the topic.