APIs and Contracts

An API (Application Programming Interface) is how one piece of software talks to another. When your mobile app fetches a user's profile, it makes an API call to your backend. When your backend charges a credit card, it makes an API call to Stripe. When you integrate with another company's platform, you consume their API. Every API is a contract: you send data in a specific format, and you receive a response in a specific format. That contract must remain stable or everything breaks.

REST (Representational State Transfer) is the dominant API architecture for web services. A RESTful API uses standard HTTP methods: GET to retrieve data, POST to create, PUT or PATCH to update, DELETE to remove. Resources are identified by URLs, like /users/123 or /orders/456. REST APIs are stateless — each request contains all the information needed to process it. The server does not remember previous requests. This simplicity is why REST won.

GraphQL is an alternative to REST that lets clients request exactly the data they need. Instead of hitting /users/123 and getting back a fixed set of fields, a GraphQL client specifies which fields it wants: just the name and email, or the full profile including order history. This eliminates over-fetching (getting data you do not need) and under-fetching (making multiple requests to assemble a view). The trade-off is complexity: GraphQL requires more sophisticated server infrastructure and client tooling.

Versioning is how you evolve an API without breaking existing clients. When you need to change a response format or remove a field, you create a new version — /v2/users instead of /v1/users. Old clients keep using v1 until they migrate. The alternative is breaking changes: deploying a new API format and forcing every client to update simultaneously. Breaking changes cause outages and angry customers. Versioning is an operational tax you pay to avoid breaking the contract.

Rate limiting is how you prevent abuse and ensure fair access to your API. Every client gets a quota: 1000 requests per hour, or 100 per minute. Exceed the quota and you get a 429 error. Without rate limits, a single misbehaving client can consume all your server capacity. With poorly designed rate limits, legitimate users hit the ceiling during normal usage. Setting the right limits requires understanding your actual traffic patterns, not guessing.

Authentication and authorization are distinct concerns. Authentication is proving who you are: logging in with a username and password, presenting an API key, exchanging an OAuth token. Authorization is proving what you are allowed to do: can this user view this resource, modify it, delete it? Many security breaches happen because systems authenticate correctly but fail to authorize — they verify identity but do not check permissions.

API documentation is not optional. If your API is undocumented, it does not exist — developers will not use it, or they will use it wrong and blame you when it breaks. Good documentation specifies every endpoint, every parameter, every possible response code, and provides working code examples in multiple languages. Documentation that is out of sync with the actual API is worse than no documentation because it creates false confidence.

Webhooks invert the API model: instead of clients repeatedly polling your API to check for updates, your server pushes updates to the client when something happens. When a payment succeeds, Stripe sends a webhook to your server. When a user signs up, your auth service sends a webhook to your notification service. Webhooks reduce load and latency, but they require clients to expose an endpoint and handle retries when delivery fails.