You Are the Client

Module 5 of 5 in the chapter The Client and Server, chapter 2 of the Integration Architect course. Each module stands on its own. Previous: The Client–Server Tango · Next chapter: APIs, Contracts and Data Across the Wire

The question this module answers: How do you make your first call to an API, and how do you read what comes back?

So far in this chapter, you’ve been watching other systems dial. Now it’s your turn. In this module, you are the client.

An API Client Makes You the Client

If you’re becoming an integration architect, you need an API tool. When I ask a class what they use, the answers come quickly: Postman, Insomnia, SoapUI for SOAP calls, Advanced REST Client, and more. Postman is the one most people use. Pick any one of them; this module works with all of them.

An API client is a tool that dials for you. You give it an address, you press Send, and it makes the call. No code, no login. And the moment you press Send, you’re the client from this chapter: you dial, and you own the round trip.

In this course, I teach the request, not the tool. Every API client shows the same things, in nearly the same places: the method, the address, the headers, the body, and then the status and the time. Learn those once, and you can sit down at any of them.

Your First Call

For the first call, we need a server that anyone can call, with no login. We’ll use httpbin.org, a free public test server, described on its own page as “A simple HTTP Request & Response Service” (httpbin.org (opens in a new tab), checked 2026-11-01). What makes it useful is that it sends your request back to you. Whatever you send, you get to see.

In your API client:

1. Start a new request, and set the method to GET.
2. Type the address: https://httpbin.org/get?delivery=D-1042
3. Press Send.

That delivery=D-1042 on the end is a Steve Trucking delivery number. httpbin doesn’t know anything about deliveries. It’s there so you can watch it come back.

Here’s the call as text, the way it travels. Your tool writes the request for you:

GET /get?delivery=D-1042 HTTP/2
Host: httpbin.org
User-Agent: (your API client's name and version)
Accept: */*

And here’s what comes back:

HTTP/2 200
content-type: application/json
content-length: 256

{
  "args": {
    "delivery": "D-1042"
  },
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "(your API client's name and version)"
  },
  "method": "GET",
  "origin": "203.0.113.10",
  "url": "https://httpbin.org/get?delivery=D-1042"
}

The origin is the public address your call came from. Yours will show your own; the one here is an address set aside for examples.

Click to enlarge

One call, as every API client shows it: what you send, and what comes back.

Read What Came Back

Look first at the status: 200 OK. That’s the server’s answer, in the words the contract gives it: it worked. Status codes are defined in the standard for HTTP (RFC 9110 (opens in a new tab), section 15), so servers everywhere are meant to use the same numbers for the same meanings.

Then look at the time. Your tool shows how long the call took, probably a few hundred milliseconds. That number is the whole round trip: out to the server, the server’s work, and back to you. Remember the last module: only the client sees the whole round trip. Here it is, on your screen. The server can’t show you that number. Only you can see it.

Then look at the body. It’s your own request, sent back: the method, the address, and your delivery number, under args. And look at the headers. You didn’t type User-Agent or Accept. Your API client added them for you. That’s worth noticing early: the server only ever knows what the client actually sends, and some of that, the tool decides.

Now Break It, on Purpose

Now make three more calls. Each one shows a different kind of answer, and each one has an owner.

A slow answer. Call https://httpbin.org/delay/3. The server waits about three seconds, then answers 200 OK. Watch the time. Your client waited the whole three seconds, because it owns the round trip. How long a client should wait before it gives up is a decision, and it’s the client’s to make.

The server said no. Make a typing mistake on purpose: https://httpbin.org/getx. This time the status is 404 Not Found. The server heard you. It looked, it found nothing at that address, and it answered with an error the contract defines. That’s the server fulfilling the contract when things don’t go well, the way it should.

No answer at all. Now call https://httpbin.invalid/get. The name .invalid is reserved so that it can never exist (RFC 6761 (opens in a new tab), section 6.4). Your tool won’t show a status at all. It will tell you it couldn’t connect. The server never heard the phone ring. There’s nobody to blame on the other side, because there was no other side. That’s a connection error, and the client has to trace it.

Click to enlarge

Three answers, and no answer. A status is the server’s answer, good or bad.

That’s the whole chapter, on your own screen. A status, good or bad, means the server got the call and answered. No status means the call never got there, and that’s on the client’s side of the dance.

Your Lab Bench

Save these four calls together, in a collection or folder called Steve Trucking. It’s the start of your lab bench, and we’ll add to it through the course: in chapter 3 you’ll bring in a contract, in chapter 8 you’ll call Salesforce, and in chapter 12 you’ll sign in properly.

Two habits to start now:

• Never send real data to a public test server. httpbin is someone else’s server. Anything you send lands there, and you don’t know who keeps it. Use made-up values, like a delivery number that doesn’t exist.
• Never paste a secret or a token into AI. There’s no secret in this module, because there’s no login. From chapter 8 on, there will be, and chapter 12 covers how to keep them safe.

Where This Goes Next

You’ve now dialed, found a server, and read its answer. Next, we take the request apart. When you’re dealing with REST, there are three places to put things: the address you’re going to, the body you’re sending, and the headers. Chapter 3 goes through each one, and the contract that says what goes where.

What an Architect Decides Here

• Which API client the team uses, so everyone can share the same calls.
• That test calls go to test servers, with made-up data, never real customers’ data.
• For every client, how long it waits for an answer before it gives up.
• How each kind of answer is handled: success, an error the server sent back, and no answer at all.

Beyond the exam: what AI changes. AI can write these calls for you: describe what you want, and it drafts the request. But the API client is where you find out what the server actually does. AI writes the first draft; the tool shows you what really happened. In chapter 3, AI goes further, and drafts a whole contract from a sample payload.

Explore

• httpbin.org (opens in a new tab): the public test server used in this module, with more addresses to try (checked 2026-11-01).
• IETF, HTTP Semantics (RFC 9110) (opens in a new tab), section 15: what each status code means.
• IETF, Special-Use Domain Names (RFC 6761) (opens in a new tab): why .invalid can never be reached.
• The next chapter, APIs, Contracts and Data Across the Wire: taking the request apart.