API Fundamentals

What is an API?

An API (Application Programming Interface) is a set of rules and protocols that allows different software applications to communicate with each other. Think of it as a waiter in a restaurant—you (the client) tell the waiter (the API) what you want, and the waiter brings back your order from the kitchen (the server).

APIs are everywhere in modern software development. When you check the weather on your phone, post on social media, or make an online payment, you're using APIs behind the scenes.

Types of APIs

Web API Architectures

// REST API Example
GET /api/users/123        // Get user 123
POST /api/users           // Create new user
PUT /api/users/123        // Update user 123
DELETE /api/users/123     // Delete user 123

// GraphQL Query Example
query {
  user(id: 123) {
    name
    email
    posts {
      title
    }
  }
}

// WebSocket Example
const socket = new WebSocket('wss://api.example.com/ws');

socket.onmessage = (event) => {
  console.log('Received:', event.data);
};

socket.send('Hello Server!');

HTTP Request/Response Cycle

Every API call follows a request/response pattern:

// HTTP Request Structure
{
  method: "GET",                    // HTTP Method
  url: "https://api.example.com/users",  // Endpoint URL
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer token123"
  },
  body: {                           // For POST/PUT/PATCH
    "name": "John Doe",
    "email": "john@example.com"
  }
}

// HTTP Response Structure
{
  status: 200,                      // Status Code
  statusText: "OK",                 // Status Message
  headers: {
    "Content-Type": "application/json",
    "X-RateLimit-Remaining": "99"
  },
  body: {                           // Response Data
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

HTTP Methods

Your First API Call

Let's make a real API call using JavaScript's Fetch API:

// Fetching data from a public API
async function getUsers() {
  try {
    // Make the API request
    const response = await fetch('https://jsonplaceholder.typicode.com/users');
    
    // Check if request was successful
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    
    // Parse JSON response
    const users = await response.json();
    
    // Use the data
    console.log('Users:', users);
    
    // Display first user
    users.forEach(user => {
      console.log(`- ${user.name} (${user.email})`);
    });
    
    return users;
  } catch (error) {
    console.error('Failed to fetch users:', error);
  }
}

// Call the function
getUsers();

/*
Output:
Users: [{id: 1, name: "Leanne Graham", ...}, ...]
- Leanne Graham (Sincere@april.biz)
- Ervin Howell (Shanna@melissa.tv)
...
*/

Common API Terms