APIs

An API (Application Programming Interface) is a defined contract that specifies how software components communicate: what requests can be made, in what format, and what responses to expect. APIs are the standard mechanism by which services, applications, and systems interoperate.

Think of a restaurant. You don't go into the kitchen and cook your food. Instead, you use a menu: a defined interface. You pick from the available options, make your request using the expected format (speak to the waiter), and get back a response (your food). An API is exactly that — a menu for software. It defines what requests another program can make, what format those requests must be in, and what it will get back. When a weather app on your phone shows the forecast, it's calling a weather API. When you pay with your card online, the website calls a payment API. When you log in with Google, there's a Google authentication API involved. APIs are how all modern software talks to other software.

The problem Software systems need to communicate. A mobile app needs data from a server. One company's system needs to trigger an action in another company's system. Without a standard way to do this, every integration would require custom, brittle code. What APIs are An API is a formal specification of how one piece of software can talk to another. It defines: - What operations are available (endpoints or methods) - What input format is required (parameters, headers, request body) - What output format to expect (response structure) - What errors might be returned The dominant style: REST REST (Representational State Transfer) uses HTTP and is the most common API style for web services: - Resources are identified by URLs: `https://api.example.com/users/123` - HTTP verbs indicate the action: GET (read), POST (create), PUT/PATCH (update), DELETE (delete) - Data is typically exchanged as JSON A concrete example ``` GET https://api.openweathermap.org/data/2.5/weather?q=London → { "weather": [{"description": "light rain"}], "main": {"temp": 15.2} } ``` Why APIs matter APIs enable the entire modern tech ecosystem. Stripe's payment API lets any website accept credit cards. Twilio's API adds SMS to any application. The AWS S3 API lets any program store files in the cloud. Without APIs, every company would have to rebuild these capabilities themselves.

API styles comparison REST (Representational State Transfer) - Stateless HTTP; each request is self-contained - Resources at URLs; CRUD via HTTP verbs - JSON or XML responses - Documented via OpenAPI/Swagger specification - Most widely used for public APIs GraphQL - Single endpoint; clients specify exactly which fields they need - Eliminates over-fetching and under-fetching - Strongly typed schema; introspection built in - Better for client-driven data needs; more complex caching gRPC - Protocol Buffers (binary serialization) over HTTP/2 - Strongly typed via .proto schema files - Bidirectional streaming; lower latency than REST - Better for internal service-to-service communication WebSockets - Full-duplex, persistent connection - Low latency, server-initiated messages - Used for real-time features: chat, live dashboards, collaborative editing API design principles - Versioning: `v1`, `v2` in the URL path or as a header — never break existing consumers - Pagination: Cursor-based (stable, handles inserts) or offset-based (simpler) - Rate limiting: Protect against abuse; communicate limits via response headers - Idempotency: POST endpoints that create resources should accept an `Idempotency-Key` header to safely retry on network failure - Error responses: Use HTTP status codes correctly; return structured error bodies with machine-readable codes Authentication patterns - API keys: Simple but no user context; good for server-to-server - OAuth 2.0: Delegated authorization; industry standard for user-acting-on-behalf - JWT: Signed tokens encoding claims; stateless verification - mTLS: Mutual TLS for high-security service-to-service

API as a product Public APIs are products with their own lifecycle. Design decisions made in v1 are expensive to undo because breaking changes break customers. Invest in: - A clear versioning strategy before launch - A deprecation policy with minimum notice periods - Backward compatibility by default (additive changes are safe; removing fields is breaking) - API governance: a review process for schema changes Internal vs. external APIs External (public) APIs require more stability guarantees, authentication, rate limiting, and documentation. Internal APIs between owned services can evolve faster but benefit from contracts enforced via schema registries (Protobuf, Avro, OpenAPI) and contract testing. Reliability patterns - Retry with exponential backoff: For idempotent requests; avoid retry storms - Circuit breaker: Stop calling a failing downstream API; fail fast locally; try again after a recovery period - Timeout: Always set explicit timeouts on outbound API calls; no request should block indefinitely - Bulkhead: Isolate API consumers in separate connection pools so one slow API doesn't starve all others API gateway A gateway (Kong, AWS API Gateway, Nginx) centralizes: authentication, rate limiting, routing, request/response transformation, logging, and observability. Useful when multiple services share cross-cutting concerns. Security - Validate all input on the server — never trust client-supplied data - Use HTTPS everywhere; never expose APIs over plain HTTP - Scope API keys/tokens to minimum necessary permissions - Log all API calls with actor, timestamp, action, and resource — for audit and forensics - Protect against mass assignment: whitelist accepted fields in update operations Observability Track: latency (p50, p95, p99), error rate, throughput, per-endpoint breakdown. Set SLOs (e.g., p99 latency < 500ms, error rate < 0.1%) and alert on SLO burn rate. Distributed tracing (OpenTelemetry) correlates API calls across service boundaries.