Api Literacy

Making Your First API Call: The Hands-On Version

Rza

— 4 min read

Reading about APIs is like reading about swimming — useful for about five minutes, after which you need to get in the water. This article walks through making an actual API call from scratch. Not a hypothetical one. A real request to a real endpoint that returns real data. By the end, you'll have done the thing that every automation tool, every integration, every connected service does under the hood — sent an HTTP request and read the response.

What The Docs Say

The documentation for any API starts by telling you the base URL (where the API lives), the available endpoints (what you can ask for), the required authentication (how to prove who you are), and the response format (what comes back). Good documentation includes example requests and example responses. Great documentation has a "Try it" button that lets you make the call right from the docs page. Most documentation falls somewhere between "adequate" and "clearly written by someone who already knows how this works."

For this walkthrough, we're going to use JSONPlaceholder — a free, public API designed specifically for testing and learning. No signup. No API key. No billing. You send a request, you get fake data back. It's a sandbox, and that's exactly what you need right now. The base URL is https://jsonplaceholder.typicode.com. The endpoint we'll hit is /posts/1, which returns a single fake blog post.

The documentation says: send a GET request to https://jsonplaceholder.typicode.com/posts/1 and you'll receive a JSON object containing the post's userId, id, title, and body. Simple enough. Let's do it.

What Actually Happens

You need a tool to send the request. Two options: Postman (a free application with a visual interface) or curl (a command-line tool built into every Mac and Linux system, and available on Windows). Postman is friendlier if you've never used a terminal. Curl is faster once you're comfortable with the command line. Neither is wrong. I'll show both.

With curl: Open your terminal (on Mac, search for "Terminal" in Spotlight). Type the following and hit enter:

curl https://jsonplaceholder.typicode.com/posts/1

That's it. One command. What comes back looks something like this:

{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur..."
}

You just made an API call. The request was a GET to that URL. The response is a JSON object — a structured text format where data is organized in key-value pairs inside curly braces. "title" is the key, the long Latin-looking string is the value. The \n characters are line breaks. The whole thing is one object representing one fake blog post.

With Postman: Download Postman (free tier works), open it, and create a new request. Set the method to GET (it's a dropdown, probably already set to GET). Paste https://jsonplaceholder.typicode.com/posts/1 in the URL field. Click Send. The response appears in the lower panel — the same JSON, but nicely formatted with syntax highlighting and collapsible sections. Postman also shows you the status code (200 OK), the response time, and the response size.

Now modify the request. Change the URL to https://jsonplaceholder.typicode.com/posts/2. Send it again. You get a different post. Change it to /posts (without a number) — you get an array of 100 posts. An array looks like a JSON object wrapped in square brackets [ ] — it's a list. Change the method from GET to POST and add a body with a title and body field — you've just "created" a post (it won't actually persist on the server, but the API responds as if it did, returning the object you sent with an assigned ID).

This modification cycle — change a parameter, observe the different response — is how you explore any API. It's not theory. It's empirical. You poke at it and see what happens, guided by the documentation.

Reading JSON: The response format deserves a moment because you'll be reading a lot of it. JSON — JavaScript Object Notation — is the lingua franca of APIs. Curly braces { } wrap objects (collections of key-value pairs). Square brackets [ ] wrap arrays (ordered lists of items). Keys are always strings in double quotes. Values can be strings, numbers, booleans (true/false), null, nested objects, or arrays. That's the entire syntax. Once you can read those patterns, you can read any API response.

The practical skill is finding the data you actually want in a potentially large response. A Stripe payment object might have 40 fields — you probably care about amount, status, and customer. A Ghost post response includes metadata, authors, tags, HTML content, and publication timestamps — you might only need the title and html. Knowing how to scan the JSON structure and extract the relevant fields is more useful than memorizing every possible field.

When To Use This

The direct API call — via curl, Postman, or the HTTP Request node in your automation tool — is the universal fallback. It works when a pre-built integration doesn't exist, when the integration doesn't expose the endpoint you need, when you need to debug a failing connection, or when you're evaluating a new service and want to understand what its API actually returns before committing to a workflow.

Postman in particular is a legitimately useful debugging tool even if you never plan to write code. When a workflow in n8n or Zapier fails with an API error, you can reproduce the exact same request in Postman — same URL, same headers, same body — and see the raw response. This often reveals what went wrong faster than staring at an error message in the automation tool's log.

The confidence takeaway is worth stating explicitly: what you just did — sending a GET request and reading a JSON response — is what every developer tool does under the hood. Zapier's Gmail integration sends GET requests to Gmail's API and parses the JSON responses. n8n's Slack node sends POST requests to Slack's API with JSON bodies. The visual interface is a wrapper. The underlying operation is the operation you just performed. You're not learning to code. You're learning to read the language that no-code tools speak when they think you're not listening.

When To Skip This

If your automation tool has native integrations for every service you use, and those integrations cover every endpoint you need, you don't need to make manual API calls. The integration does it for you, handles authentication automatically, and presents the response in a usable format. Direct API calls are the escape hatch, not the primary door.

That said — the escape hatch gets used more than people expect. The first time a native integration doesn't support a specific endpoint (for example, Zapier's Ghost integration might not support updating custom properties on a post), you'll reach for the HTTP Request action and build the call yourself. When that moment comes, this article is your playbook: find the endpoint in the docs, build the request (URL + method + headers + body), send it, read the response, iterate. The pattern never changes, no matter how complex the API.

This is part of CustomClanker's API Literacy series — the thing nobody explains before you try to connect two tools.

Read more