APIs Explained: How Applications Communicate With Each Other

1. The Core Purpose of an API

An Application Programming Interface (API) is a formalized set of rules, definitions, and communication protocols that allow one software component to interact with another. Rather than requiring direct access to a database or internal memory structures, an API provides a clean abstraction layer that exposes only authorized operations.

2. REST Architecture Principles

Formulated by Roy Fielding in his 2000 doctoral dissertation, REpresentational State Transfer (REST) defines a stateless client-server architectural style:

• Statelessness: Every single request from client to server must contain all of the contextual information and authentication tokens necessary to process the request. No session state is held on the server.
• Uniform Interface: Resources are identified by standard URIs (e.g., /api/v1/users/42) and manipulated using standard HTTP verbs.
• Cacheability: Responses must explicitly define whether they can be cached downstream (via Cache-Control and ETag headers).

3. HTTP Methods and Status Codes

RESTful services leverage HTTP verbs semantically:

• GET — Safe and idempotent retrieval of a resource.
• POST — Creation of a new subordinate resource.
• PUT — Full idempotent replacement of a resource.
• PATCH — Partial modification of a resource.
• DELETE — Idempotent removal of a resource.

4. Payloads & Data Contracts: JSON Serialization

While older APIs utilized verbose XML or SOAP specifications, modern web APIs overwhelmingly standardize on JSON (JavaScript Object Notation):

{
  "id": "usr_9912",
  "username": "jvance",
  "status": "active",
  "created_at": "2026-10-10T14:32:00Z"
}

5. Authentication Patterns: API Keys and Bearer Tokens

Stateless APIs authenticate incoming requests via HTTP headers:

• API Keys: Passed via X-API-Key: secret_abc123. Suitable for server-to-server communication.
• Bearer Tokens (JWT): Passed via Authorization: Bearer <token>. JSON Web Tokens are digitally signed cryptographic strings containing user claims and expiration times.

6. Pagination and Rate Limiting Mechanics

When querying large datasets (e.g. 50,000 log records), dumping all records into a single response exhausts memory buffers. APIs use pagination:

Cursor-Based Pagination: Superior to offset-based pagination because it uses immutable record pointers:

GET /api/v1/events?limit=25&cursor=evt_1048

Rate Limiting: Enforces capacity ceilings (e.g., 100 requests per minute) using Token Bucket or Sliding Window algorithms, returning:

HTTP/2 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
Retry-After: 45

7. Webhooks: Event-Driven Push Notifications

Instead of forcing a client to poll an API every 5 seconds asking "Has a payment succeeded yet?", webhooks invert control. When an event fires, the provider transmits an HTTP POST payload to a designated URL on the client server.

To prevent spoofing, webhook providers sign the payload using a shared secret and an HMAC-SHA256 signature header (e.g., X-Signature), which the receiving server verifies before processing.

8. Practical API Testing with `curl`

# Test an authenticated POST request with JSON payload:
$ curl -X POST https://api.rootnode.dev/v1/articles \
  -H "Authorization: Bearer secret_token_xyz" \
  -H "Content-Type: application/json" \
  -d '{"title": "How APIs Work", "category": "web-dev"}' \
  -i

9. Frequently Asked Questions