DEV Community

Cover image for REST APIs: What They Are and How to Use Them
APIVerve
APIVerve

Posted on • Originally published at blog.apiverve.com

REST APIs: What They Are and How to Use Them

#restapi #http #webdev #beginners

You've heard the term "REST API" thrown around. Maybe you nodded along in a meeting pretending you knew what it meant. No judgment — we've all been there.

Here's the thing: REST APIs aren't complicated. They're just a way for programs to talk to each other over the internet. That's it. The jargon makes it sound scarier than it is.

By the end of this article, you'll make real API requests and actually understand what's happening. Let's get into it.

What's Actually Happening When You "Call an API"

When you type a URL in your browser and hit enter, you're making an API request. Seriously. Your browser sends a request to a server, and the server sends back HTML.

REST APIs work the same way, except instead of HTML, you get data — usually JSON. And instead of just "getting" pages, you can create, update, and delete things too.

Your Code  →  HTTP Request  →  Server  →  HTTP Response  →  Your Code
Enter fullscreen mode Exit fullscreen mode

That's the whole mental model. Everything else is details.

Why "REST"?

REST stands for Representational State Transfer. You don't need to memorize this. What matters is the practical stuff:

  • Stateless: Every request is independent. The server doesn't remember your previous requests.
  • Resource-based: You're working with "things" (users, products, emails) at specific URLs.
  • Standard HTTP: Uses the same protocol your browser uses. No special setup.

The Four HTTP Methods You'll Actually Use

REST APIs use HTTP methods to tell the server what you want to do. There are technically more, but these four handle 99% of cases:

GET — "Give me this thing" 

// Get a random joke
const response = await fetch('https://api.apiverve.com/v1/randomjoke', {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data.data.joke);
// "Why don't scientists trust atoms? Because they make up everything!"
Enter fullscreen mode Exit fullscreen mode

GET requests retrieve data. They don't change anything on the server. You can make the same GET request 100 times and get the same result (unless the data changed for other reasons).

POST — "Create this new thing" 

// Validate an email address
const response = await fetch('https://api.apiverve.com/v1/emailvalidator', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: 'test@example.com'
  })
});

const data = await response.json();
console.log(data.data.isValid); // true or false
Enter fullscreen mode Exit fullscreen mode

POST requests send data to the server to create something or trigger an action. The request body contains the data you're sending.

PUT — "Replace this thing entirely" 

// Update a user profile (hypothetical example)
fetch('https://api.example.com/users/123', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Jane Doe',
    email: 'jane@example.com',
    role: 'admin'
  })
});
Enter fullscreen mode Exit fullscreen mode

PUT replaces the entire resource. If you leave out a field, it's gone. For partial updates, some APIs use PATCH instead.

DELETE — "Remove this thing" 

fetch('https://api.example.com/users/123', {
  method: 'DELETE'
});
Enter fullscreen mode Exit fullscreen mode

Does what it says. The resource is gone.

Making Your First Real API Request

Enough theory. Let's make an actual request that returns real data.

Step 1: Get an API Key

Most APIs require authentication. It's how they know who's making requests (and who to bill).

For this example, grab a free APIVerve key — takes 30 seconds, no credit card.

Step 2: Make the Request

Let's look up information about an IP address:

async function lookupIP(ipAddress) {
  const response = await fetch(
    `https://api.apiverve.com/v1/iplookup?ip=${ipAddress}`,
    {
      headers: {
        'x-api-key': 'YOUR_API_KEY'
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }

  return response.json();
}

// Try it
const result = await lookupIP('8.8.8.8');
console.log(result);
Enter fullscreen mode Exit fullscreen mode

Step 3: Understand the Response

Here's what you get back:

{
  "status": "ok",
  "error": null,
  "data": {
    "ip": "8.8.8.8",
    "city": "Mountain View",
    "region": "California",
    "country": "United States",
    "countryCode": "US",
    "isp": "Google LLC",
    "timezone": "America/Los_Angeles",
    "lat": 37.4056,
    "lon": -122.0775
  }
}
Enter fullscreen mode Exit fullscreen mode

That's it. You just called an API. The response is JSON — a structured format that's easy to work with in any programming language.

HTTP Status Codes: What the Numbers Mean

When something goes wrong (and it will), the status code tells you why.

The Good Ones

  • 200 OK — Worked perfectly
  • 201 Created — You made a new thing, and it worked
  • 204 No Content — Worked, but there's nothing to send back (common with DELETE)

You Messed Up

  • 400 Bad Request — Your request was malformed. Check your JSON syntax.
  • 401 Unauthorized — Missing or invalid API key
  • 403 Forbidden — Valid API key, but you don't have permission for this
  • 404 Not Found — That resource doesn't exist
  • 422 Unprocessable Entity — The request was valid JSON, but the data was wrong (like an invalid email format)
  • 429 Too Many Requests — Slow down, you're hitting rate limits

The Server Messed Up

  • 500 Internal Server Error — Something broke on their end. Not your fault.
  • 502 Bad Gateway — Server couldn't reach an upstream service
  • 503 Service Unavailable — Server is overloaded or down for maintenance

Here's a simple way to handle them:

async function makeRequest(url, options) {
  const response = await fetch(url, options);

  if (response.ok) {
    return response.json();
  }

  // Handle specific errors
  switch (response.status) {
    case 401:
      throw new Error('Check your API key');
    case 429:
      throw new Error('Rate limited - wait and retry');
    case 404:
      throw new Error('Resource not found');
    default:
      throw new Error(`Request failed: ${response.status}`);
  }
}
Enter fullscreen mode Exit fullscreen mode

Common Mistakes (And How to Avoid Them)

Forgetting the Content-Type Header 

// Wrong - server doesn't know you're sending JSON
fetch(url, {
  method: 'POST',
  body: JSON.stringify({ email: 'test@example.com' })
});

// Right
fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ email: 'test@example.com' })
});
Enter fullscreen mode Exit fullscreen mode

Not Handling Errors 

// Dangerous - assumes everything works
const data = await fetch(url).then(r => r.json());

// Better - check before parsing
const response = await fetch(url);
if (!response.ok) {
  throw new Error(`HTTP ${response.status}`);
}
const data = await response.json();
Enter fullscreen mode Exit fullscreen mode

Exposing API Keys in Client-Side Code

If your JavaScript runs in a browser, anyone can see your API key. Use a backend proxy:

// Bad - API key visible in browser
fetch('https://api.apiverve.com/v1/iplookup', {
  headers: { 'x-api-key': 'sk_live_abc123' } // Anyone can see this!
});

// Good - call your own backend, which has the key
fetch('/api/lookup-ip', {
  method: 'POST',
  body: JSON.stringify({ ip: '8.8.8.8' })
});
Enter fullscreen mode Exit fullscreen mode

Your backend then makes the real API call with the key safely hidden.

Query Parameters vs Request Body

Two ways to send data. Knowing when to use each saves debugging time.

Query Parameters (in the URL)

Used with GET requests. Good for filters, search terms, pagination.

// Get jokes in a specific category
fetch('https://api.apiverve.com/v1/randomjoke?category=programming')
Enter fullscreen mode Exit fullscreen mode

Request Body (in the payload)

Used with POST/PUT. Good for creating or updating complex data.

// Validate an email with detailed options
fetch('https://api.apiverve.com/v1/emailvalidator', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@domain.com'
  })
})
Enter fullscreen mode Exit fullscreen mode

Rule of thumb: GET uses query params, POST/PUT uses body. Some APIs break this rule, so always check the docs.

Try These APIs

Want to practice? Here are some beginner-friendly APIs you can call right now:

API What it does Try it
Random Joke Returns a random joke Great for testing
Email Validator Checks if an email is valid Useful in forms
IP Lookup Gets location from IP Good for personalization
QR Code Generator Creates QR codes Visual output

All of these work with the same authentication pattern. Learn one, you've learned them all.

What's Next?

You now know enough to work with most REST APIs. The concepts don't change — just the specific endpoints and data shapes.

A few paths forward:

The best way to learn is to build something. Pick an API, make it do something useful, and the rest will click.

Originally published at APIVerve Blog

Top comments (0)