The Client–Server Tango

Module 4 of 5 in the chapter The Client and Server, chapter 2 of the Integration Architect course. Each module stands on its own. Previous: Knocking on the Door · Next: You Are the Client

The question this module answers: In a single call, what is the client responsible for, what is the server responsible for, and where does each one’s job stop?

There’s a dance to every call. I call it the client–server tango.

I picked the tango because almost everyone has a picture of it: two partners, close together, moving as one. I’ve taken dance lessons, and one of the first things you learn is that the two partners don’t do the same steps. Each one has their own part, and the parts are different. Danced alone, either part looks a little strange. Danced together, by two people who each know their own part, it looks like one dance.

A call works the same way. The client has its moves, and the server has its moves. They aren’t the same moves, and neither side can dance the other’s part. When both know their moves, the call just works. When one side thinks a move belongs to the other, the dance falls apart, and that’s usually where the long night of debugging starts.

So let’s learn the two parts, side by side.

Each Side’s Dance Moves

The client, the one that dials, has to:

• know the endpoint: the name and the port, from Finding the Server;
• maybe go to a second server first, to get its token, from Knocking on the Door;
• speak the server’s protocol, which gives it the contract: what are the verbs, get orders; what are the nouns, orders, customers;
• pack the payload the way the server expects. That packing has a name, serialization, and chapter 3 takes it apart;
• and own the whole round trip, there and back.

The server, the one that answers, has to:

• make itself available, at an IP address or a name;
• keep a process up and listening for connections, most likely a web server, on 443 if it’s secure, or on a port it has chosen and published;
• run the server that issues tokens, or use one from someone else;
• define the protocol, the contract and the way the payload is packed. The client follows; the server decides;
• debug its own internal processing, log it, and validate what comes in;
• and when it finally releases the answer, its responsibility stops.

Click to enlarge

The tango: two parts, each with its own moves. Neither one can dance the other’s part.

The Client Owns the Round Trip

Here’s where the two parts differ most. In this dance, the client takes the first step, and the client is the one still there at the end, waiting to know the dance is done. The server’s part happens in the middle.

That’s why this is the move people get wrong most often. If there’s a problem anywhere in the round trip, it’s the client’s to debug.

If the client can’t connect, that’s the client’s problem, not the server’s. The server never even heard the phone ring. And if the server sent its answer in one second, but it took 29 more seconds to reach the client, that’s the client’s problem too. The server did its job in a second. Everything that happened on the way there and back is on the client’s side of the dance.

Why? Because only the client sees the whole round trip. The server knows what it received and what it did with it. What it can’t see is whether its answer ever made it back. The client can. That’s the same reason the caller calls back when the line drops, in the first module.

So the client is responsible for tracing:

• connection errors: it couldn’t find the server, or nobody was listening;
• sign-in errors: its credentials or its token were refused;
• server errors passed back: the server tried, and told it something went wrong;
• response errors: an answer came back, but not one it could use, or not in time.

Every one of those needs a decision on the client’s side: where do I log it, what do I tell the user, and how do I retry? Those are the questions from chapter 1, and this is where they live.

The Server Owns What Happens Inside

The server’s part is the middle of the dance: everything between the call arriving and the answer leaving. And it goes in order.

1. It receives a request that has already been authenticated. It knows who’s calling, from Knocking on the Door.
2. It examines the payload: is this what the contract describes?
3. It makes sure the request is valid: from a caller allowed to ask for this, with everything the request needs.
4. It attempts the processing.

If something goes wrong inside, that’s the server’s own internal error. The server logs it in its own logs, with all the detail it needs, so that when a client says “something went wrong at 2:14,” the server can find exactly what it received and what happened. It can debug every step, because it’s all on its side.

But the client doesn’t get those internal details. It doesn’t need them, and usually it shouldn’t see them. What the client gets back is an answer it can act on: one of a set of error messages that the contract defines.

That’s the part people forget. The contract isn’t only for success. The server has to fulfill the contract both ways. When the work succeeds, it sends back what the contract promised. When it fails, it sends back one of the errors the contract promised, so the client knows what happened and what to do next. In the next module, you’ll see one of those answers come back.

Then it releases the answer, and its responsibility stops. That’s the boundary from Owners, Boundaries and Change in chapter 1, drawn on a single call. Every arrow crosses a line between owners, and the tango is how you say, out loud, where that line is.

Both Clients and Both Servers

One more thing about the dance. In a dance class, you sometimes swap and learn the other part. In integration, systems swap parts all the time. Client and server aren’t kinds of system. They’re parts in a call. If system A calls system B, and system B calls system A, they are both clients and both servers.

Here’s Redrock and Salesforce again, from the first module.

Click to enlarge

Call 1: Redrock dials. Redrock is the client, Salesforce the server.

Click to enlarge

Call 2: Salesforce dials. Now Salesforce is the client, and Redrock the server.

Same two systems, two calls, and the moves swap with them. For call 2, it’s Salesforce that has to know Redrock’s address, hold the credentials to sign in to it, and own that round trip. It’s Redrock that has to be listening. So on a project, I don’t write “Salesforce is the server.” I write it per arrow: for this call, who’s the client?

And notice how fast this adds up. Two systems can have two calls between them; every system you add brings more. Chapter 5 does that math, and it’s one of the best arguments for putting something in the middle.

What an Architect Decides Here

• For every arrow, which system is the client and which is the server, written down per call, not per system.
• On the client’s side: where each kind of error is logged, what the user is told, and how it retries.
• On the server’s side: the contract it defines, what it validates, what it logs inside, and the errors it promises in the contract as well as the successes.
• Where each side’s responsibility stops, agreed with the other side’s owner before go-live.
• For two systems that call each other, which credentials each holds for the other, and who owns each round trip.

Beyond the exam: what AI changes. When an AI agent calls a tool, the agent is the client, and it owns the round trip like any client. If the tool times out or sends back an error, the agent has to know that it failed, not guess an answer and carry on. Chapter 21 comes back to what that means for agents.

Explore

• The Data Architect course, Proof of Delivery: the client owns the conversation, and who proves the data arrived.
• Chapter 1, Owners, Boundaries and Change: where each side’s responsibility stops.
• The next module, You Are the Client: make your first call.