APIs

Overview

An API (Application Programming Interface) is a contract that lets one piece of software talk to another without knowing its internals. In system design, APIs define how clients and services request data and trigger actions. A clear, stable API keeps systems loosely coupled and easier to evolve.

Syntax / Usage

The most common web API style is REST, which maps HTTP methods to actions on resources identified by URLs. Responses are usually JSON, and status codes signal success or failure.

GET    /users        -> list users
GET    /users/42     -> fetch user 42
POST   /users        -> create a user
PUT    /users/42     -> replace user 42
DELETE /users/42     -> delete user 42

200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error

Good APIs are versioned (for example /v1/users), documented, and consistent in naming.

Examples

A mobile app calls POST /v1/orders with a JSON body to place an order; the server responds 201 Created and a JSON object containing the new order's id.

A public weather service exposes GET /v1/forecast?city=London, returning JSON. Because the data is read-only and changes slowly, responses can be cached to reduce load.

Common Mistakes

• Returning 200 OK for errors instead of proper status codes
• Breaking existing clients by changing responses without versioning
• Exposing internal database fields directly in the API
• Not paginating list endpoints, causing huge responses
• Inconsistent naming (/getUser vs /users) across endpoints

See Also

system-design-client-server system-design-fundamentals system-design-caching