APIs and Data Exchange Formats

What Is an API?

An API (Application Programming Interface) is a set of rules, protocols, and tools that allows different software applications to communicate with each other. APIs define the methods and data formats that programs can use to request and exchange information, acting as a contract between a service provider and a service consumer.

Think of an API as a waiter in a restaurant: you (the client) make a request from the menu, the waiter (the API) takes your request to the kitchen (the server), and brings back what you ordered. You do not need to know how the kitchen works — you just need to know how to place the order correctly.

APIs come in several forms: Web APIs (HTTP-based, the most common today), Library/SDK APIs (functions exposed by a code library), Operating System APIs (system calls for file I/O, networking, etc.), and Hardware APIs (interfaces for interacting with physical devices). This article focuses primarily on web APIs, which power the modern internet.

REST Architecture

REST (Representational State Transfer) is an architectural style for designing networked applications, introduced by Roy Fielding in his 2000 doctoral dissertation. RESTful APIs are the dominant style for web APIs due to their simplicity, scalability, and alignment with HTTP.

A RESTful API adheres to these core principles:

• Client-Server: The client and server are separated, allowing them to evolve independently. The client handles the UI; the server handles data storage and business logic.
• Stateless: Each request contains all the information needed to process it. The server does not store client context between requests.
• Cacheable: Responses must explicitly indicate whether they can be cached, improving performance and reducing server load.
• Uniform Interface: Resources are identified by URIs (e.g., /api/users/123), manipulated through standard HTTP methods, and represented in standard formats (JSON, XML).
• Layered System: The architecture can include intermediaries (load balancers, proxies, gateways) without the client knowing.

Resources in REST are nouns, not verbs. You use /api/users (not /api/getUsers), and the HTTP method determines the action. This uniformity makes REST APIs predictable and self-documenting.

HTTP Methods

HTTP methods (also called verbs) define the type of action to perform on a resource. In REST APIs, each method maps to a specific CRUD (Create, Read, Update, Delete) operation:

Method	CRUD Operation	Idempotent?	Safe?	Example
GET	Read	Yes	Yes	GET /api/users/123 — Retrieve user 123
POST	Create	No	No	POST /api/users — Create a new user
PUT	Update (replace)	Yes	No	PUT /api/users/123 — Replace user 123 entirely
PATCH	Update (partial)	No	No	PATCH /api/users/123 — Update specific fields
DELETE	Delete	Yes	No	DELETE /api/users/123 — Remove user 123
HEAD	Read (headers only)	Yes	Yes	HEAD /api/users/123 — Check if resource exists
OPTIONS	Discover	Yes	Yes	OPTIONS /api/users — List allowed methods

Idempotent means calling the same request multiple times produces the same result as calling it once. Safe means the method does not modify the resource. GET and HEAD are both safe and idempotent, making them ideal for caching and retries.

Request and Response Structure

An HTTP request to a REST API consists of several components:

HTTP Request:

POST /api/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json

{
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "admin"
}

HTTP Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/users/123
Cache-Control: no-cache

{
  "id": 123,
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "admin",
  "created_at": "2024-06-15T10:30:00Z"
}

Key components of a request include the method, URL/path, headers (metadata like content type, authentication), optional query parameters (e.g., ?page=2&limit=20), and the request body (for POST, PUT, PATCH). Responses include a status code, headers, and a response body.

HTTP Status Codes

HTTP status codes are three-digit numbers that indicate the result of a request. They are grouped into five categories by their first digit:

Code	Name	Category	Meaning
200	OK	2xx Success	Request succeeded. Response body contains the result.
201	Created	2xx Success	Resource created. Location header usually contains the new URI.
204	No Content	2xx Success	Request succeeded but no response body (common for DELETE).
301	Moved Permanently	3xx Redirect	Resource has permanently moved to a new URL.
304	Not Modified	3xx Redirect	Cached version is still valid (conditional request).
400	Bad Request	4xx Client Error	Malformed syntax, invalid data, or missing required fields.
401	Unauthorized	4xx Client Error	Authentication required or token is invalid/expired.
403	Forbidden	4xx Client Error	Authenticated but lacking permission for this action.
404	Not Found	4xx Client Error	Resource does not exist at the specified URI.
405	Method Not Allowed	4xx Client Error	HTTP method is not supported for this endpoint.
409	Conflict	4xx Client Error	Request conflicts with current state (e.g., duplicate entry).
422	Unprocessable Entity	4xx Client Error	Syntax is correct but semantically invalid (validation error).
429	Too Many Requests	4xx Client Error	Rate limit exceeded. Retry after the specified time.
500	Internal Server Error	5xx Server Error	Unexpected server-side error. The client did nothing wrong.
502	Bad Gateway	5xx Server Error	Upstream server returned an invalid response.
503	Service Unavailable	5xx Server Error	Server is temporarily overloaded or under maintenance.
504	Gateway Timeout	5xx Server Error	Upstream server did not respond in time.

A well-designed API returns the appropriate status code for every scenario. Avoid returning 200 for everything with an error message in the body — use proper 4xx and 5xx codes so clients can handle errors programmatically.

Data Exchange Formats Compared

While JSON dominates modern APIs, several data formats are in active use. The choice depends on performance requirements, ecosystem support, and use case:

Format	Type	Size	Parse Speed	Human Readable	Primary Use
JSON	Text	Medium	Fast	Yes	REST APIs, config files, web apps
XML	Text	Large	Moderate	Yes	SOAP APIs, documents, enterprise systems
Protocol Buffers	Binary	Small	Very Fast	No	gRPC, high-performance microservices
MessagePack	Binary	Small	Very Fast	No	Real-time apps, IoT, gaming
YAML	Text	Medium	Slow	Yes	Config files (Docker, Kubernetes, CI/CD)
CSV	Text	Small	Fast	Yes	Tabular data, spreadsheets, data exports
GraphQL	Text (JSON)	Variable	Fast	Yes	Flexible queries, avoiding over-fetching

Protocol Buffers (protobuf) are Google's binary serialization format. They require a .proto schema definition file and generate code in multiple languages. Protobuf is significantly smaller and faster than JSON, making it ideal for internal microservice communication where every millisecond counts.

API Authentication Methods

Most APIs require authentication to identify the caller and enforce access control. The most common methods are:

Method	How It Works	Best For	Security Level
API Key	A unique string passed in a header or query parameter	Simple server-to-server calls	Basic (key can be leaked)
OAuth 2.0	Token-based authorization with access/refresh tokens	User-facing apps, third-party integrations	High (industry standard)
JWT (JSON Web Token)	Signed token containing claims, passed in Authorization header	Stateless authentication, microservices	High (when properly implemented)
Basic Auth	Base64-encoded username:password in header	Internal tools, simple setups	Low (credentials in every request)
mTLS	Mutual TLS — both client and server present certificates	Zero-trust environments, service mesh	Very High

The Authorization header is the standard way to send credentials: Authorization: Bearer <token> for OAuth/JWT, or Authorization: Basic <base64> for Basic Auth. Never embed API keys in URLs (they appear in server logs) — always use headers.

Rate Limiting and Best Practices

Rate limiting protects APIs from abuse, ensures fair usage, and maintains service stability. When a client exceeds the allowed number of requests, the API returns a 429 Too Many Requests status code.

Common rate limiting strategies:

• Fixed Window: Allow N requests per time window (e.g., 100 requests per minute). Simple but can cause burst traffic at window boundaries.
• Sliding Window: A rolling time window that smooths out traffic spikes. More predictable than fixed window.
• Token Bucket: Tokens are added at a fixed rate; each request consumes a token. Allows controlled bursts while maintaining an average rate.
• Leaky Bucket: Requests are queued and processed at a constant rate, smoothing out bursts entirely.

APIs communicate rate limit status through response headers:

X-RateLimit-Limit: 100        # Maximum requests per window
X-RateLimit-Remaining: 47     # Requests left in current window
X-RateLimit-Reset: 1718459200 # Unix timestamp when the window resets
Retry-After: 30               # Seconds to wait (sent with 429 response)

API design best practices:

• Use plural nouns for resource names (/users, not /user).
• Version your API in the URL (/api/v1/users) or via header.
• Return consistent error formats with a machine-readable error code and human-readable message.
• Support pagination for list endpoints (?page=1&limit=20).
• Use HATEOAS links to guide clients through available actions.
• Document your API with OpenAPI/Swagger specifications.
• Implement proper CORS headers for browser-based clients.

Understanding APIs and data exchange formats is essential for modern development. Whether you are consuming third-party APIs or building your own, following these standards ensures interoperability, security, and a good developer experience. Use our API Tester tool to test HTTP requests and inspect responses.