API

Explanation

An API abstracts implementation behind a stable interface. Calling Math.random() uses an API — you don't care how randomness is generated; you know the contract (call it, get a number between 0 and 1). The same principle scales: OS APIs, library APIs, and web APIs all apply this pattern. Web APIs are what most developers mean today: a server accepting HTTP requests and returning structured data (usually JSON). These power mobile apps, SPAs, and service-to-service communication. REST, GraphQL, gRPC, and WebSockets are all patterns for implementing web APIs. API design is about contracts: once published and consumed, changing an API can break dependents. API versioning (/v1/users, /v2/users in the URL, or via headers) allows breaking changes without breaking existing clients. Changelogs, deprecation notices, and semantic versioning are part of responsible API maintenance. Internal vs. external APIs: internal APIs are consumed within your organization (frontend calling backend, microservice to microservice). External (public) APIs are consumed by third parties and require stricter versioning, documentation, authentication, rate limiting, and SLA commitments.

Code Example

// API consumer: calling a third-party API
async function getWeather(city) {
  const url = 'https://api.openweathermap.org/data/2.5/weather';
  const params = new URLSearchParams({
    q: city,
    appid: process.env.WEATHER_API_KEY,
    units: 'metric',
  });
  const res = await fetch(`${url}?${params}`);
  if (!res.ok) throw new Error(`Weather API: ${res.status} ${res.statusText}`);
  const data = await res.json();
  return { temp: data.main.temp, description: data.weather[0].description };
}

// API provider: versioned endpoint
app.get('/api/v1/users/:id', async (req, res) => {
  const user = await User.findById(req.params.id);
  if (!user) return res.status(404).json({ error: 'Not found' });
  res.json({ id: user.id, name: user.name, email: user.email });
});

// Add a new version for breaking changes — v1 clients unaffected
app.get('/api/v2/users/:id', async (req, res) => {
  // v2: returns additional fields
  const user = await User.findByIdWithProfile(req.params.id);
  if (!user) return res.status(404).json({ error: 'Not found' });
  res.json(user);
});

Why It Matters for Engineers

APIs are the fundamental building block of modern software. Every mobile app calls APIs; every SaaS integration uses APIs; every microservice communicates via APIs. Understanding API design — contracts, versioning, authentication, error handling — is essential for any backend or full-stack engineer. API design decisions are long-lived: once an API has consumers, changing it requires coordinating with all of them. Designing clean APIs from the start prevents years of technical debt. This is an area where AI-generated code often falls short — generating APIs without versioning, inconsistent error formats, and non-RESTful URL structures.