How to Use a Public API

What is an API?

An API (Application Programming Interface) is a contract that lets one piece of software talk to another over a network. Most APIs in this directory are HTTP REST APIs: you send a request to a URL, the server returns JSON, and your code processes the result.

Every API has its own conventions. Before writing any code, open the docs and look for: the base URL, the authentication scheme, available endpoints, request/response formats, rate limits, and pricing tiers (yes — even "free" APIs can have caps).

Authentication

APIs in this directory are tagged with one of these auth types. Each has different implications for how you build and where you store credentials.

HTTPS

Always prefer APIs that support HTTPS. Plain HTTP transmits requests, headers, and responses in cleartext — anyone on the network path can read or modify them. If an API is listed as HTTPS-only in the directory badge, you're already covered.

CORS — when it matters

CORS (Cross-Origin Resource Sharing) only matters when calling an API directly from browser JavaScript. The badge tells you what to expect:

• Yes — you can call it from a frontend with fetch().
• No — the browser will block the request. You'll need a backend proxy or serverless function in between.
• Unknown — try it. If the browser console shows Access-Control-Allow-Origin errors, you'll need a proxy.

Server-to-server calls (Node, Python, Go, etc.) are never affected by CORS — it's purely a browser security model.

Rate Limits

Almost every free API has limits — requests per second, per minute, or per day. Hitting them returns 429 Too Many Requests. Build for it from day one:

• Read the X-RateLimit-* response headers when present.
• Cache responses you'll re-use within their freshness window.
• Implement exponential backoff: on a 429, wait 1s, 2s, 4s, 8s before retrying.
• Batch requests where the API supports it instead of looping one-by-one.

Errors & Status Codes

Don't trust the network. Connections drop, services go down, and even a 200 response can contain garbage. Always check the status:

Security & Secret Handling

The single biggest mistake when starting out is leaking an API key. Avoid it:

• Never put keys in client-side JavaScript. Anything shipped to a browser is public. Use a backend, edge function, or serverless proxy.
• Store secrets in environment variables (.env) and add .env to .gitignore.
• If you accidentally commit a key — rotate it immediately. Just deleting the commit isn't enough; git history is forever.
• Use the minimum scope. If an OAuth API offers read-only tokens, never request write.

Your First Request

A minimal example using fetch in modern JavaScript:

async function getJoke() {
  const res = await fetch('https://icanhazdadjoke.com/', {
    headers: {
      Accept: 'application/json',
      'User-Agent': 'my-app/1.0 (https://example.com)',
    },
  });

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

  const data = await res.json();
  return data.joke;
}

The same pattern in Python:

import requests

def get_joke():
    res = requests.get(
        'https://icanhazdadjoke.com/',
        headers={
            'Accept': 'application/json',
            'User-Agent': 'my-app/1.0 (https://example.com)',
        },
        timeout=10,
    )
    res.raise_for_status()
    return res.json()['joke']

Useful Tools

Pre-flight Checklist

Before shipping any integration, make sure you can answer "yes" to each of these:

• I read the official docs, not just a blog post.
• I'm using HTTPS.
• My API key is in an environment variable, not source code.
• I handle non-200 responses without crashing.
• I respect rate limits and back off on 429s.
• I cache responses where it makes sense.
• I have a plan for when the API is down.
• I monitor my usage so I know before I hit a quota.