API Versioning and Security Basics: Authentication, Rate Limiting, and HTTPS
Once an API goes live, other programs start calling it. If you rename a field or change the response format, every old caller may break. So "how to evolve after launch" and "how to prevent abuse" are the two required lessons of API design. This article covers versioning, authentication, rate limiting, and HTTPS.
1. Why Versioning Matters
Software evolves, and so do APIs — but callers cannot upgrade at the same pace. Versioning adds a "compatibility layer": old and new versions coexist, old users keep using v1, new features ship in v2, and everyone gets what they need without breaking anyone.
Suppose your order API needs to change from "return the whole order" to "paginated results". Changing it directly would break old callers. The right move is to release a v2, let old callers keep using v1, and only take v1 down after they migrate. A typical migration window is 6-12 months.
2. Two Main Versioning Approaches
1. URL path versioning: put the version in the path, e.g. https://api.example.com/v2/orders. It is intuitive and cache-friendly, but one URL maps to only one version. This is the default choice for most teams.
2. Header versioning: put the version in a header, e.g. Accept: application/vnd.example.v2+json. The URL stays clean, but it is harder to debug and cache, and operators cannot see the version at a glance.
Comparison:
| Aspect | URL Path Versioning | Header Versioning |
|---|---|---|
| Readability | High, visible at a glance | Low, hidden in a header |
| Cache-friendly | Yes | No |
| Ease of use | Simple | More complex |
| When to use | Default for most teams | When a clean URL is a priority |
Either way the core rule is the same: once v1 ships, never delete or mutate it — only add, and announce removals well in advance. For full API design rules, see RESTful API Design Best Practices.
3. Comparing Three Authentication Methods
Not just anyone should be able to call your API. You need to prove "who you are and what you may do". The three most common authentication methods:
| Method | How It Works | Pros | Cons | Best For |
|---|---|---|---|---|
| API Key | A secret key sent with each request | Simple, fast to adopt | Keys can leak; hard to revoke one user | Internal tools, server-to-server |
| Basic Auth | username:password Base64-encoded | Minimal, browser-native | Plaintext by design, needs HTTPS | Temporary debugging |
| OAuth2 | An authorization server issues a token | Fine-grained scopes, revocable, mature standard | Complex; needs an authorization server | Third-party user-facing apps |
Key point: API keys and Basic Auth were never designed for secure transport — the credential is essentially a plaintext "key". They must be paired with HTTPS, otherwise the key is hanging on the front door. For user-facing login and authorization, prefer OAuth2. See API Security with OAuth/JWT and JWT Authentication Implementation Guide.
4. Rate Limiting: A Faucet for Your API
Rate limiting controls how many requests are allowed per time window, preventing a single caller from overwhelming your server. It is also one of the most effective ways to stop malicious scraping. A common implementation is the token bucket: a fixed number of "tokens" is added each second, one token is consumed per request, and once the bucket is empty new requests are rejected.
A typical config: 60 requests per minute per user (1 per second). Beyond that, return 429 Too Many Requests and tell the caller when to retry (e.g. Retry-After: 30). A sensible rate limit reduces the chance of being knocked over and helps control cost.
5. HTTPS: A Must for APIs
HTTPS has been mentioned repeatedly, and it is not a "suggestion" but a "requirement". Three reasons: it prevents data from being read in transit (passwords, tokens, order details); it prevents content from being tampered with; and many browsers and systems block non-HTTPS endpoints outright. For how HTTPS and certificates work, see What Is HTTPS. Authentication, rate limiting, and encryption together make a secure API — see also Web Security Hardening Guide.
6. FAQ
Q1: When can I finally take v1 down? Track v1 traffic. When it has been near zero for 1-2 months and you have announced the shutdown on your site for at least 30 days, you can consider it.
Q2: My API key leaked, what now? Revoke it and generate a new one immediately, then check access logs for any abnormal calls before the leak. Always keep keys in server-side environment variables, never in frontend code.
Q3: Won't rate limiting hurt legitimate users? It can, so leave headroom — set the threshold at roughly 2-3x your peak call rate — and give callers a clear 429 message plus a retry mechanism.
Q4: Do small projects need OAuth2? Not necessarily. If it is two services within your own product, API Key + HTTPS is enough. You only need OAuth2 when third parties must log in to your platform.
7. Summary
One line: versioning protects old users, authentication decides who gets in, rate limiting stops you being hammered, and HTTPS secures the transport. Do all four and your API is ready to face the public. For more, bookmark the Backend Integration category.