What Is an API? A Simple Developer Guide with Examples

The Anatomy of an API Request

Every web API interaction consists of a request originating from a client (a browser, mobile app, or backend server) and a response returned by a host server.

An HTTP request contains four critical components: the endpoint URL, the HTTP method, request headers (defining format and credentials), and an optional request body.

• Endpoint URL: The unique destination address (e.g. https://api.github.com/users/octocat).
• HTTP Method: Specifies the intended action (GET to read, POST to create, PUT to update, DELETE to remove).
• Headers: Metadata passing content format (application/json) and security credentials.
• Payload / Body: The JSON data string transmitted with state-changing requests.

[Client Application]
       │
       │  1. HTTP GET https://api.weather.com/v1/forecast?city=Tokyo
       │     Headers: { Authorization: "Bearer xyz", Accept: "application/json" }
       ▼
[Cloud API Gateway / Server]
       │
       │  2. Processes database query & serializes payload
       ▼
[Client Application]
       ▲
       │  3. HTTP 200 OK
       │     Body: { "temperature": 18, "condition": "Sunny" }
       └─────────────────────────────────────────────┘

Making a Real API Call in JavaScript

Modern JavaScript uses the native fetch() API with async/await to request and parse JSON from remote endpoints.

// Requesting public user data from the GitHub REST API
async function fetchUserProfile(username) {
  try {
    const response = await fetch(`https://api.github.com/users/${username}`, {
      headers: {
        'Accept': 'application/json'
      }
    });

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

    const userData = await response.json();
    console.log(`User: ${userData.name} | Public Repos: ${userData.public_repos}`);
    return userData;
  } catch (error) {
    console.error('API request failed:', error.message);
  }
}

fetchUserProfile('torvalds');

The 3 Main Types of APIs You Will Encounter

REST (Representational State Transfer): The dominant web architecture relying on standard HTTP verbs, stateless requests, and JSON payloads.

GraphQL: A query language developed by Meta allowing clients to specify precisely which fields they need, eliminating over-fetching.

WebSocket APIs: Full-duplex persistent connections ideal for real-time tickers, multiplayer games, and chat applications.