From URL to JSON in five minutes

No theory in this one. We’re going to pick an API, get a key, and pull real JSON into your terminal, first with curl and then from a tiny Node script. If you have a shell open, this genuinely takes about five minutes.

Pick an API

Open the catalog and choose something with data you recognize. For this walkthrough I’ll use the Hacker News API, because the responses are small and you can eyeball whether they’re right. Every API page lists its endpoints, their parameters, and a sample response, so you know the shape before you write a line of code.

We’ll hit the “top stories” endpoint. In maviapi’s URL scheme that’s under /v1/sites/hacker-news/, and it takes an optional limit.

Get a key

Calls to the data endpoints need a key. Sign in, open your keys, and create one. You’ll see the full key exactly once, because we only ever store a hash of it, so copy it somewhere safe right away. Then put it in your shell so you’re not pasting it into every command:

export MAVIAPI_KEY="sk_live_your_key_here"

Your first call with curl

One request, one header for auth:

curl https://api.maviapi.com/v1/sites/hacker-news/top?limit=3 \
  -H "Authorization: Bearer $MAVIAPI_KEY"

You get back clean, already-structured JSON, not a wall of HTML to parse:

{
  "stories": [
    {
      "id": 41284001,
      "title": "Show HN: I turned my favourite website into an API",
      "url": "https://example.com/show",
      "by": "patio11",
      "score": 412,
      "comments": 138
    }
  ]
}

Notice there’s no scraping on your side, no headless browser, no CAPTCHA to wrangle. You asked for three stories and got three stories.

The same call from Node

Nothing exotic here either. fetch is built into modern Node, so there’s no SDK to install to get going:

const res = await fetch(
  "https://api.maviapi.com/v1/sites/hacker-news/top?limit=3",
  { headers: { Authorization: `Bearer ${process.env.MAVIAPI_KEY}` } }
);

if (!res.ok) {
  throw new Error(`maviapi returned ${res.status}`);
}

const { stories } = await res.json();
for (const s of stories) {
  console.log(`${s.score.toString().padStart(4)}  ${s.title}`);
}

Run it with node top-stories.mjs and you’ve got a three-line front page in your terminal. From here it’s ordinary code: drop the data in a database, post it to Slack, render it on a page. The hard part, getting clean data out of a website, is already done.

Where to go next

A few things worth knowing once the first call works:

• Check the response headers. x-maviapi-version tells you which build served you, and the rate-limit headers tell you how much room you have left.
• Read the rate-limit guide before you put anything in a loop. A client that backs off politely is one you never have to babysit.
• Can’t find the site you want? Use the “request an API” flow and the build agent will stand one up. The same five-minute path works for it the moment it’s ready.