API Versioning: Maintaining Backward Compatibility

API Versioning: Maintaining Backward Compatibility

APIs change over time: fields added, endpoints removed, behavior modified. Old clients expect old behavior; new clients expect new behavior. Versioning ensures both work simultaneously. Without versioning, breaking change (removing field) breaks all old clients using it. With versioning, old clients use v1, new clients use v2.

Versioning Approaches

URL Path: /api/v1/users (all v1 endpoints in v1 path). /api/v2/users (v2 endpoints in v2 path). Pro: Clear separation. Con: Duplicate code. Request Header: /api/users with header Accept: application/json;version=2. Pro: Single URL. Con: Less obvious. Query Parameter: /api/users?api_version=2. Pro: Easy to test in browser. Con: Not standard. Media Type: Accept: application/vnd.myapi.v2+json. Pro: RESTful. Con: Complex. Most common: URL path versioning. Simple, clear, explicit.

Backward Compatibility

Old clients must continue working. API v1 returns: { "id": 1, "name": "John", "email": "john@example.com" }. v2 adds "age": 25. v1 client ignores new field "age". Still works. v2 removes "email" field. v1 client expects "email". Fails. Breaking change. Solution: Keep fields, mark deprecated. v2 response: { "id": 1, "name": "John", "email": "john@example.com", "age": 25, "email": "(deprecated, use contact.email)" }. Old client gets "email", still works.

v1 Implementation

Basic endpoints: GET /api/v1/users (list users). GET /api/v1/users/{id} (get user). POST /api/v1/users (create user). PUT /api/v1/users/{id} (update user). DELETE /api/v1/users/{id} (delete user). Response: { "id": 1, "name": "John", "email": "john@example.com" }. Pagination: GET /api/v1/users?page=1&page_size=10. Error response: { "error": "Not found" }. Status codes: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Server Error.

v2 Evolution

Requirements: Add user profile with bio, social links. Remove deprecated fields. Restructure responses for clarity. v2 response: { "id": 1, "name": "John", "contact": { "email": "john@example.com", "phone": null }, "profile": { "bio": "Software engineer", "social_links": { "twitter": "john_dev" } } }. Contact field introduced (v1 kept email at top level). Profile field new. Email moved to contact. Error response enhanced: { "error": "validation_failed", "details": { "email": "Invalid email format" } }. Specific error codes instead of generic "error".

Deprecation Strategy

v1 release: /api/v1/users (no deprecation). v2 release: /api/v2/users (v1 still works). In v2 response headers: Deprecation: true; sunset=date (date v1 support ends). Documentation warns: v1 deprecated, migrate to v2. v2.1 release: Announce v1 sunset date 6 months away. v2.5 release: Actually remove v1. Wait time ensures clients migrate before removal. Communication: Blog posts, email to API users, documentation.

Handling Multiple Versions

Backend routes: @app.route('/api/v1/users'); def v1_list_users(): return v1_format(get_users()). @app.route('/api/v2/users'); def v2_list_users(): return v2_format(get_users()). Shared logic: def get_users(): return fetch_from_db(). Format differently: v1_format adds top-level email; v2_format nests in contact. Tests for each version: test_v1_user_response(), test_v2_user_response(). Both pass.

Database Migrations

v1 schema: CREATE TABLE users (id INT, name VARCHAR, email VARCHAR). v2 adds columns: ALTER TABLE users ADD COLUMN age INT, ADD COLUMN bio TEXT. Database supports both. v1 queries: SELECT id, name, email FROM users (columns exist). v2 queries: SELECT id, name, email, age, bio FROM users (all columns). Backward compatible at database level.

API Gateway Versioning

Large systems: API gateway routes to versioned backend services. Client request: GET /api/v2/users. API Gateway: Check URL version = 2. Route to: backend-v2-service. backend-v2-service returns response. Gateway returns to client. If v1 requested: Route to backend-v1-service. Multiple versions coexist, each with own backend service. Backend services can optimize for their version without affecting others.

API Documentation

Each version documented separately. v1 docs: "email field at top level". v2 docs: "email field under contact". Changelog: "v2.0: Restructured user response, email moved to contact". Deprecation notices: "As of v2, email field deprecated, use contact.email". SDKs: Version-specific SDKs. npm install my-api-client-v2. SDKs encapsulate API details, client code simpler.

Testing Versions

Integration tests for each version: def test_v1_list_users(): response = client.get('/api/v1/users'); assert response.status_code == 200; assert 'email' in response.json()[0]. def test_v2_list_users(): response = client.get('/api/v2/users'); assert response.status_code == 200; assert 'contact' in response.json()[0]; assert 'email' in response.json()[0]['contact']. Both pass, versions work independently. End-to-end tests: Test workflow with v1, same workflow with v2. Both succeed (backward compatibility proven).

Sunset Timeline

Typical lifecycle: v1 released; v2 released 6 months later with deprecation notice; v1 supported 12 months from v2 release; v1 removed. Communicate timeline early; set expectations. Monitor usage: How many clients still on v1? If 5%, sunset easier. If 50%, extend timeline. Provide migration guides: "Migrate from v1 to v2 in 5 steps". Tools to help: Automated schema validator (for v1 and v2). Deprecation warnings in responses help clients identify upgrade timing.

Under the Hood: API Versioning: Maintaining Backward Compatibility

Here is what separates someone who merely USES technology from someone who UNDERSTANDS it: knowing what happens behind the screen. When you tap "Send" on a WhatsApp message, do you know what journey that message takes? When you search something on Google, do you know how it finds the answer among billions of web pages in less than a second? When UPI processes a payment, what makes sure the money goes to the right person?

Understanding API Versioning: Maintaining Backward Compatibility gives you the ability to answer these questions. More importantly, it gives you the foundation to BUILD things, not just use things other people built. India's tech industry employs over 5 million people, and companies like Infosys, TCS, Wipro, and thousands of startups are all built on the concepts we are about to explore.

This is not just theory for exams. This is how the real world works. Let us get into it.

Neural Networks: Layers of Learning

A neural network is inspired by how your brain works. Your brain has billions of neurons connected to each other. When you see, hear, or think something, electrical signals flow through these connections. A neural network simulates this with layers of mathematical operations:

  INPUT LAYER          HIDDEN LAYERS          OUTPUT LAYER
  (Raw Data)           (Feature Extraction)    (Decision)

  Pixel 1 ──┐
  Pixel 2 ──┤    ┌─[Neuron]─┐
  Pixel 3 ──┼───▶│ Edges &   │───┐
  Pixel 4 ──┤    │ Corners   │   │    ┌─[Neuron]─┐
  Pixel 5 ──┤    └───────────┘   ├───▶│ Face     │──▶ "It's a cat!" (92%)
  ...       │    ┌─[Neuron]─┐   │    │ Features │      "It's a dog" (7%)
  Pixel N ──┤    │ Shapes & │───┘    │ + Body   │      "Other" (1%)
             └───▶│ Textures │───────▶│ Shape    │
                  └───────────┘       └──────────┘

  Layer 1: Detects simple features (edges, gradients)
  Layer 2: Combines into complex features (eyes, ears, whiskers)
  Layer 3: Makes the final decision based on all features

Each connection between neurons has a "weight" — a number that determines how important that connection is. During training, the network adjusts these weights to minimise errors. This is done using an algorithm called backpropagation combined with gradient descent. The loss function measures how wrong the network is, and gradient descent follows the slope downhill to find better weights.

Modern networks like GPT-4 have billions of parameters (weights) and are trained on massive GPU clusters. India's Sarvam AI is training models specifically for Indian languages — Hindi, Tamil, Telugu, Bengali, and more — because global models often perform poorly on Indic scripts and cultural contexts.

Real-World System Design: Swiggy's Architecture

When you order food on Swiggy, here is what happens behind the scenes in about 2 seconds: your location is geocoded (algorithms), nearby restaurants are queried from a spatial index (data structures), menu prices are pulled from a database (SQL), delivery time is estimated using ML models trained on historical data (AI), the order is placed in a distributed message queue (Kafka), a delivery partner is assigned using a matching algorithm (optimization), and real-time tracking begins using WebSocket connections (networking). EVERY concept in your CS curriculum is being used simultaneously to deliver your biryani.

Algorithm Complexity and Big-O Notation

Big-O notation describes how an algorithm's performance scales with input size. This is THE most important concept for coding interviews:

  BIG-O COMPARISON (n = 1,000,000 elements):

  O(1)        Constant     1 operation          Hash table lookup
  O(log n)    Logarithmic  20 operations        Binary search
  O(n)        Linear       1,000,000 ops        Linear search
  O(n log n)  Linearithmic 20,000,000 ops       Merge sort, Quick sort
  O(n²)       Quadratic    1,000,000,000,000    Bubble sort, Selection sort
  O(2ⁿ)       Exponential  ∞ (universe dies)    Brute force subset

  Time at 1 billion ops/sec:
  O(n log n): 0.02 seconds    ← Perfectly usable
  O(n²):      11.5 DAYS       ← Completely unusable!
  O(2ⁿ):      Longer than the age of the universe

  # Python example: Merge Sort (O(n log n))
  def merge_sort(arr):
      if len(arr) <= 1:
          return arr
      mid = len(arr) // 2
      left = merge_sort(arr[:mid])      # Sort left half
      right = merge_sort(arr[mid:])     # Sort right half
      return merge(left, right)         # Merge sorted halves

  def merge(left, right):
      result = []
      i = j = 0
      while i < len(left) and j < len(right):
          if left[i] <= right[j]:
              result.append(left[i]); i += 1
          else:
              result.append(right[j]); j += 1
      result.extend(left[i:])
      result.extend(right[j:])
      return result

This matters in the real world. India's Aadhaar system must search through 1.4 billion biometric records for every authentication request. At O(n), that would take seconds per request. With the right data structures (hash tables, B-trees), it takes milliseconds. The algorithm choice is the difference between a working system and an unusable one.

Production Engineering: API Versioning: Maintaining Backward Compatibility at Scale

Understanding api versioning: maintaining backward compatibility at an academic level is necessary but not sufficient. Let us examine how these concepts manifest in production environments where failure has real consequences.

Consider India's UPI system processing 10+ billion transactions monthly. The architecture must guarantee: atomicity (a transfer either completes fully or not at all — no half-transfers), consistency (balances always add up correctly across all banks), isolation (concurrent transactions on the same account do not interfere), and durability (once confirmed, a transaction survives any failure). These are the ACID properties, and violating any one of them in a payment system would cause financial chaos for millions of people.

At scale, you also face the thundering herd problem: what happens when a million users check their exam results at the same time? (CBSE result day, anyone?) Without rate limiting, connection pooling, caching, and graceful degradation, the system crashes. Good engineering means designing for the worst case while optimising for the common case. Companies like NPCI (the organisation behind UPI) invest heavily in load testing — simulating peak traffic to identify bottlenecks before they affect real users.

Monitoring and observability become critical at scale. You need metrics (how many requests per second? what is the 99th percentile latency?), logs (what happened when something went wrong?), and traces (how did a single request flow through 15 different microservices?). Tools like Prometheus, Grafana, ELK Stack, and Jaeger are standard in Indian tech companies. When Hotstar streams IPL to 50 million concurrent users, their engineering team watches these dashboards in real-time, ready to intervene if any metric goes anomalous.

The career implications are clear: engineers who understand both the theory (from chapters like this one) AND the practice (from building real systems) command the highest salaries and most interesting roles. India's top engineering talent earns ₹50-100+ LPA at companies like Google, Microsoft, and Goldman Sachs, or builds their own startups. The foundation starts here.

Key Vocabulary

Here are important terms from this chapter that you should know:

💡 Interview-Style Problem

Here is a problem that frequently appears in technical interviews at companies like Google, Amazon, and Flipkart: "Design a URL shortener like bit.ly. How would you generate unique short codes? How would you handle millions of redirects per second? What database would you use and why? How would you track click analytics?"

Think about: hash functions for generating short codes, read-heavy workload (99% redirects, 1% creates) suggesting caching, database choice (Redis for cache, PostgreSQL for persistence), and horizontal scaling with consistent hashing. Try sketching the system architecture on paper before looking up solutions. The ability to think through system design problems is the single most valuable skill for senior engineering roles.

Where This Takes You

The knowledge you have gained about api versioning: maintaining backward compatibility is directly applicable to: competitive programming (Codeforces, CodeChef — India has the 2nd largest competitive programming community globally), open-source contribution (India is the 2nd largest contributor on GitHub), placement preparation (these concepts form 60% of technical interview questions), and building real products (every startup needs engineers who understand these fundamentals).

India's tech ecosystem offers incredible opportunities. Freshers at top companies earn ₹15-50 LPA; experienced engineers at FAANG companies in India earn ₹50-1 Cr+. But more importantly, the problems being solved in India — digital payments for 1.4 billion people, healthcare AI for rural areas, agricultural tech for 150 million farmers — are some of the most impactful engineering challenges in the world. The fundamentals you are building will be the tools you use to tackle them.

Crafted for Class 7–9 • AI & Machine Learning • Aligned with NEP 2020 & CBSE Curriculum