What Is an API? Master the Basics in 10 Minutes

What an API Is

An API (Application Programming Interface) is a set of agreed‑upon rules that let different systems—front‑end apps, mobile clients, micro‑services, AI models—communicate without exposing their internal implementation.

Restaurant Analogy

When you dine, you sit, read the menu, tell the waiter what you want, the waiter passes the order to the kitchen, the kitchen prepares the dish, and the waiter returns it to you. In this analogy:

you = client / developer

kitchen = server

waiter = API

The API transports the request and response while you never touch the kitchen directly.

HTTP Request Structure

URL – the request address.

Method – the request verb (GET, POST, PUT, DELETE, …).

Header – metadata such as authentication tokens.

Body – payload data for methods that send data (POST, PUT).

Four Core HTTP Methods

GET – retrieve data without changing server state, e.g. GET /api/song/list returns the song list.

POST – create a new resource, e.g. POST /api/song/create with JSON {"name":"Blue Sky","author":"Tom"} adds a song.

PUT – update an existing resource, e.g. PUT /api/song/10 modifies the song whose ID is 10.

DELETE – remove a resource, e.g. DELETE /api/song/10 deletes that record.

CRUD Mapping

Create → POST

Read → GET

Update → PUT

Delete → DELETE

Why APIs Are Ubiquitous

Decoupling : Front‑end focuses on UI, back‑end on API logic; they can be developed independently.

Scalability : The same API can be consumed by web, Android, iOS, or mini‑programs.

Micro‑service readiness : Large systems split into services (user, order, payment, recommendation) that talk to each other through APIs.

Common API Styles and Protocols

REST – the dominant style, built on HTTP and JSON. Example endpoints: GET /api/users, POST /api/users, PUT /api/users/1, DELETE /api/users/1.

GraphQL – lets the client specify exactly which fields it needs, avoiding over‑fetching. Example query:

{
  user {
    name
    avatar
  }
}

The server returns only the requested fields, e.g. {"name":"Tom","avatar":"avatar.png"}.

SOAP – an older XML‑based protocol with strict contracts and higher security, still used in banking, ERP, and government systems.

gRPC – Google’s binary protocol that sends serialized protobuf messages. It offers lower latency, higher throughput, and is popular in cloud‑native micro‑service architectures.

Webhook – server‑initiated callbacks. Instead of the client polling (e.g., “has the payment succeeded?”), the payment platform calls the client’s endpoint when the event occurs.

WebSocket – full‑duplex, persistent connections for real‑time scenarios such as chat, live stock quotes, or game state synchronization.

WebRTC – peer‑to‑peer browser communication for video/audio streams without a relay server; used by services like Google Meet.

HTTP Status Codes

2xx – success (e.g., 200 OK).

4xx – client error (e.g., 404 Not Found, 401 Unauthorized).

5xx – server error (e.g., 500 Internal Server Error).

Practical Spring Boot Example

package com.icoderoad.controller;

import org.springframework.web.bind.annotation.*;
import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/api/user")
public class UserController {
    @GetMapping("/{id}")
    public Map<String, Object> getUser(@PathVariable Long id) {
        Map<String, Object> result = new HashMap<>();
        result.put("id", id);
        result.put("name", "Tom");
        result.put("age", 22);
        return result;
    }
}

Running the application and calling curl http://localhost:8080/api/user/1 returns:

{
  "id": 1,
  "name": "Tom",
  "age": 22
}

Real‑World API Scenarios

Map services : A food‑delivery app shows restaurant locations by calling Google Maps API instead of maintaining its own global map data.

Weather apps : The app requests current weather from a third‑party API and receives JSON such as:

{
  "city": "Tokyo",
  "temperature": 27,
  "humidity": 61,
  "windSpeed": 12
}

The app then renders the values.

Over‑Fetching and GraphQL Remedy

REST endpoints often return more fields than needed (e.g., user nickname, avatar, phone, address, email, creation time, login history). GraphQL solves this by letting the client request only the required fields, eliminating the “over‑fetch” problem.

SOAP Characteristics

Strict contract, XML payload, high security, complex configuration.

Still prevalent in banking, government, and enterprise ERP systems.

gRPC Advantages

Binary protocol → lower latency, higher throughput.

Ideal for high‑concurrency micro‑service communication.

Webhook Workflow

When a payment succeeds, the payment platform sends an HTTP POST to the merchant’s callback URL. The merchant does not need to poll the platform repeatedly.

WebSocket Use Cases

Online chat

Live stock market feeds

Multiplayer game state sync

Real‑time comment streams

WebRTC Use Cases

Video conferencing (e.g., Google Meet)

Browser‑to‑browser voice calls

Real‑time audio/video streaming without a media server.

APIs for AI and Large Models

AI services expose model inference via HTTP or gRPC APIs. For example, Netflix’s recommendation pipeline sends a JSON payload such as:

{
  "userId": 1001,
  "watchHistory": ["Sci-Fi", "Action"]
}

The model processes the request and returns a list of recommended items. The interaction is still an API call.

Learning Path

Install an HTTP client tool (Postman, Apifox) to send raw requests.

Practice with public APIs (GitHub, OpenWeather, PokeAPI) – start with GET, inspect JSON, status code, and headers.

Advance to POST/PUT/DELETE to create, modify, and delete resources.

Read API documentation thoroughly: parameters, example requests, authentication methods, response schema, and error codes.

Mastering these steps builds the “API mindset” needed to understand how modern internet systems—social apps, e‑commerce, payments, AI services, video streaming, and games—communicate.