When I started integrating systems, the acronyms scared me more than the work did. REST, SOAP, JSON, XML, WSDL. It sounded like a secret language I hadn’t been invited to learn. The truth turned out to be much gentler: REST and SOAP are simply two styles of menu for ordering requests from another system. Once you see them that way, the fear drains out and you can just pick the right tool.

So let me walk you through both, the way I wish someone had walked me through them.

An API is a menu of requests

Every API is a menu. It lists what you’re allowed to ask for (“give me this account”, “create this order”, “cancel this subscription”) and the format you must use to ask. REST and SOAP are two different conventions for how that menu is written and how you place your order. They solve the same problem — letting two systems talk — but they grew up in different decades, with different priorities.

SOAP: the formal contract

SOAP came first, and it shows. It’s older, stricter, and built around XML — a verbose, tag-heavy format. A SOAP service publishes a WSDL, which is a precise contract describing every operation, every field, and every data type. If you send a field of the wrong type, SOAP refuses you before you even finish speaking.

That strictness is not a flaw. In enterprise systems — banking, insurance, ERP platforms like SAP — that rigid contract is exactly what you want. Everyone knows the rules in advance, the structure is enforced, and there’s little room for ambiguity. The cost is weight: more ceremony, more XML, more setup.

You’ll meet SOAP when you integrate with established back-office systems, and Salesforce still offers a full SOAP API for exactly these partners.

REST: the lightweight default

REST is the younger, lighter style, and it’s where most modern integration lives. Instead of a formal contract, REST uses plain web addresses (URLs) and the ordinary verbs of the web: GET to read, POST to create, PATCH to update, DELETE to remove. The data usually travels as JSON, which is far easier on the eyes than XML.

Here’s a tiny slice of JSON describing an account — notice how readable it is:

{
  "Name": "Aksu Consulting",
  "Industry": "Education",
  "AnnualRevenue": 250000
}

That’s it. No envelopes, no schemas wrapped around schemas. You can almost read it like a sentence. For a beginner, REST is friendlier to learn, faster to test, and supported by nearly every tool you’ll touch.

If you’re starting out and nobody has told you otherwise, reach for REST. It’s the modern default, and it will carry you through the vast majority of integrations.

So which one, and when?

Let me make it simple. You rarely choose the style yourself — the system you’re connecting to chooses it for you by what it offers. Your job is to recognize which menu you’ve been handed.

  • Building something new, or connecting to a modern service (Stripe, most SaaS apps)? You’ll almost certainly use REST with JSON.
  • Connecting to an older enterprise system, especially in finance or ERP? You may have to speak SOAP with XML, and you’ll be handed a WSDL to follow.
  • Salesforce itself offers both, so you can meet each partner on its own terms.

This is a bit like accompanying a singer. If they hand me sheet music in one key, I don’t argue — I tune to them. REST and SOAP are just two keys, and a good integrator plays in whichever one the other system is singing in.

A word on what stays the same

Whichever style you use, the deeper concerns don’t change. You still have to prove who you are before the other system lets you in. You still have to plan for the request failing halfway. The style is just the surface; the engineering underneath — authentication, retries, error handling — is where the real craft lives. REST won’t save you from a network drop, and SOAP won’t save you from a system being down. Those are problems you design for on purpose, regardless of format.

That mindset — assume the request can fail and build for it — is what separates a demo from a production integration. The API style is the easy decision. Everything after it is the work.

Your next step

Now that you can tell the two menus apart, build the foundation around them. Start with Salesforce Integration for Beginners to see where APIs fit in the bigger picture, then learn how systems prove their identity in Authentication for Integrations. When you’re ready, browse the full Integration category for the rest of the journey.

Mustafa Aksu

Salesforce developer & ISV builder focused on Revenue Cloud, Agentforce, and Data Cloud. I write from real, shipped work.

See my work → Try Configra →