System Design (HLD)What Is an API?

Understanding APIs: The Foundation of Modern System Communication

LevelBeginner

Duration60 mins

TopicWhat Is an API?

4 / 4

API Lifecycle

APIs Are Forever (Or Should Be)

When Amazon launched AWS S3 in 2006, they made design decisions that persist to this day—nearly two decades later. The API paths, authentication model, and XML response format chosen by engineers in 2006 still serve millions of applications. This isn't legacy debt; it's intentional permanence. The S3 API has evolved through backward-compatible additions while maintaining unwavering support for original operations.

This is the reality of API design: decisions made today will constrain or empower your system for years or decades. Unlike internal code that can be refactored at will, APIs create external dependencies that cannot be easily unwound. The integration code your consumers write becomes technical debt that they bear—and they will resist changes that force them to modify working code.

Understanding the API lifecycle—from birth through evolution to eventual sunset—is essential for making decisions today that won't become regrets tomorrow.

What You Will Learn

You will understand the complete API lifecycle: the design phase and its long-term implications, the launch process and what 'GA' really means, the evolution strategies that maintain backward compatibility, the deprecation process and its organizational choreography, and the eventual sunset that gracefully ends API support. This knowledge enables you to make decisions that stand the test of time.

The API Lifecycle Framework

APIs progress through well-defined lifecycle stages, each with distinct characteristics, objectives, and constraints.

1.1 The Five Stages

Stage 1: Design

Define the contract based on use cases
Make foundational decisions about style, naming, error handling
Review with stakeholders and potential consumers
Duration: Weeks to months

Stage 2: Preview (Alpha/Beta)

Expose to early adopters
Gather feedback and iterate
Breaking changes are permitted (with notice)
Duration: Months

Stage 3: General Availability (GA)

Production-ready for all consumers
Full support and SLA commitments
Breaking changes only through versioning
Duration: Years to decades

Stage 4: Deprecation

Announce intention to discontinue
Provide migration path to replacement
Maintain functionality but discourage new usage
Duration: 12-24+ months

Stage 5: Sunset/Retirement

Remove access to deprecated API
Complete migration of remaining consumers
Archive documentation
Duration: Final

Converting Mermaid diagram...

1.2 Stage Duration Expectations

Lifecycle stages have dramatically different durations:

API Lifecycle Stage Durations
Stage	Typical Duration	Key Milestone	Breaking Changes?
Design	2-6 months	Contract approval	N/A (not public)
Alpha	1-3 months	Internal testing complete	Yes, expected
Beta (Private)	2-6 months	Partner validation	Yes, with notice
Beta (Public)	1-3 months	Community feedback	Reluctantly, with notice
GA	5-20+ years	Full production launch	No (use versioning)
Deprecation	12-24+ months	Zero new integrations	No
Sunset	Single date	API shutdown	Total (API removed)

The Asymmetry of Time

Design takes months; GA lasts for years or decades. The 3 months you spend in design determine the 10 years you spend in GA. This asymmetry means design investments have outsized returns—and design shortcuts have outsized costs.

The Design Phase: Decisions That Last

The design phase is where you make decisions that will persist for the lifetime of the API. Getting these right—or at least not catastrophically wrong—is critical.

2.1 Foundational Decisions

These decisions are nearly impossible to change after GA:

API Style and Protocol:

REST vs. GraphQL vs. gRPC vs. others
HTTP/1.1 vs. HTTP/2+ requirements
Streaming vs. request-response

Naming Conventions:

URL path structure (/users/123 vs /users/user_123)
Field naming (camelCase vs snake_case)
Terminology choices (what is a 'user' vs 'account' vs 'profile'?)

Authentication Model:

API keys vs. OAuth 2.0 vs. JWT
Header-based vs. query parameter vs. body
Scopes and permission model

Error Format:

Error structure (flat vs. nested)
Error codes (numeric vs. string)
Internationalization of error messages

Identifier Format:

UUID vs. sequential IDs vs. custom prefixed IDs
Opacity (can consumers infer meaning from IDs?)

Hard-to-Undo Design Decisions

•API style (REST → GraphQL)
•Authentication mechanism
•Base URL structure
•Resource naming/terminology
•ID format and opacity
•Error response structure
•Pagination approach
•Content-Type choices

Easier-to-Evolve Decisions

•Add new endpoints
•Add optional request parameters
•Add response fields
•Increase rate limits
•Add new enum values (with care)
•Add new authentication methods
•Add new SDK languages
•Improve error messages

2.2 Design Review Process

Robust design review prevents regrets:

API Design Review Checklist
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# API Design Review Checklist
 
## Pre-Review Requirements
- [ ] OpenAPI/GraphQL specification complete
- [ ] Example requests and responses for all operations
- [ ] Error cases documented
- [ ] Security model defined
- [ ] Rate limiting strategy defined
 
## Consistency Review
- [ ] Naming follows organizational conventions
- [ ] HTTP methods match operation semantics
- [ ] Response structures consistent with existing APIs
- [ ] Error format matches organizational standard
- [ ] Authentication consistent with other APIs
 
## Consumer Perspective Review
- [ ] Use cases clearly addressed
- [ ] Minimum viable operations included
- [ ] No leaky abstractions (internal details exposed)
- [ ] Sensible defaults for optional parameters
- [ ] Clear documentation for all fields
 
## Evolvability Review
- [ ] Room for future enhancements
- [ ] No unnecessary coupling to current implementation
- [ ] Pagination built in where lists may grow
- [ ] Versioning strategy defined
- [ ] Expansion patterns for response fields
 
## Security Review
- [ ] Authentication requirements appropriate
- [ ] Authorization model scalable
- [ ] Rate limiting prevents abuse
- [ ] No sensitive data in URLs or logs
- [ ] Input validation specified
 
## Operational Review
- [ ] Monitoring hooks defined
- [ ] SLA targets achievable
- [ ] Capacity planning complete
- [ ] Incident response plan
 
## Approval Gates
- [ ] API Product Manager approval
- [ ] Security team approval
- [ ] Documentation team review
- [ ] Consumer representative review (if known)

Prototype with Consumers

The best design validation is implementation. Before finalizing your design, have 2-3 potential consumers (internal or partners) build against a mock version. Their implementation struggles reveal design flaws that appear minor in specification but catastrophic in code.

Preview Phase: Learning Through Exposure

The preview phase bridges design and GA. It's your last opportunity to make breaking changes without major coordination costs.

3.1 Alpha vs. Beta

Alpha:

Very early, may be unstable
Internal testing focus
Breaking changes expected weekly
No external commitments
Feature completeness: ~60-80%

Beta:

Feature complete (or nearly so)
External early adopters invited
Breaking changes possible but documented
Beginning to form external commitments
Feature completeness: ~90-100%

3.2 Setting Expectations

Clear communication prevents frustration:

Preview API Communication
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
HTTP/1.1 200 OK
Content-Type: application/json
X-API-Status: beta
X-API-Stability: experimental
X-API-Breaking-Change-Notice: This API is in beta. Breaking changes
    may occur with 2 weeks notice. Subscribe to changelog for updates.
 
{
    "data": { ... },
    "_meta": {
        "apiStatus": "beta",
        "stabilityLevel": "experimental",
        "breakingChangePolicy": "2 weeks notice via changelog",
        "changelogUrl": "https://changelog.example.com/beta-api",
        "feedbackEmail": "api-beta@example.com"
    }
}

3.3 Feedback Collection

The preview phase's primary value is learning. Active feedback collection is essential:

Quantitative feedback:

API usage patterns (which endpoints, frequencies)
Error rates by endpoint and error type
Latency distributions
Funnel metrics (signup → first call → production)

Qualitative feedback:

Developer interviews (what was hard?)
Support tickets (what confuses people?)
Community questions (what's unclear?)
Integration reviews (how did code turn out?)

3.4 When to Move to GA

GA Readiness Criteria

•Stability demonstrated — No breaking changes for 4+ weeks
•Performance validated — Latency and throughput meet targets at scale
•Error rates acceptable — 5xx errors < 0.1%
•Documentation complete — Full API reference, guides, examples
•SDKs ready — Official SDKs for major languages tested
•Support structure — Support channels operational
•SLA defined — Uptime and response time commitments ready
•Monitoring complete — Dashboards and alerts operational
•Consumer validation — At least 3 consumers in production successfully

Don't Rush to GA

Premature GA is extremely costly. Once you commit to stability, every design flaw becomes permanent technical debt. It's far better to extend beta by 2 months than to live with a bad decision for 10 years. Resist pressure to launch before you're ready.

General Availability: The Long Commitment

General Availability (GA) is a commitment. When you declare an API GA, you're promising:

Stability: No breaking changes without versioning
Support: Production-level support and SLAs
Longevity: Years of continued availability

4.1 What GA Means

GA is NOT:

Just removing the 'beta' label
A marketing milestone
The end of development

GA IS:

A contractual commitment to stability
The beginning of long-term maintenance
Elevated operational requirements
Restricted change flexibility

4.2 Backward Compatibility Promise

The core GA promise is backward compatibility: existing integrations continue to work. This means:

Backward Compatible vs. Breaking Changes
Change Type	Example	Compatible?
Add optional field to request	Add `metadata` object to POST body	✅ Yes
Add field to response	Add `createdAt` to user object	✅ Yes
Add new endpoint	Add `GET /users/{id}/preferences`	✅ Yes
Add new HTTP method	Add `PATCH /users/{id}`	✅ Yes
Widen accepted values	Accept both 'USD' and 'usd'	✅ Yes
Remove field from request	Remove `name` requirement	⚠️ Usually (test)
Remove field from response	Remove `legacyStatus`	❌ Breaking
Rename field	Rename `user_id` to `userId`	❌ Breaking
Change field type	Change `age` from string to int	❌ Breaking
Add required field	Require `email` on all requests	❌ Breaking
Remove endpoint	Remove `DELETE /deprecated`	❌ Breaking
Change error format	Change error structure	❌ Breaking
Stricter validation	Reject previously accepted values	❌ Breaking

Additive Evolution Pattern
1
2
3
4
5
6
7
// Original GA response (2020)
{
    "id": "usr_123",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "status": "active"
}

The Robustness Principle

Also known as Postel's Law: 'Be conservative in what you send, liberal in what you accept.' Clients should ignore unknown response fields. Servers should be lenient with optional inputs. This mutual tolerance enables evolution on both sides.

Versioning Strategies for Breaking Changes

When breaking changes are unavoidable, versioning allows them without disrupting existing consumers.

5.1 Versioning Approaches

URL Path Versioning:

https://api.example.com/v1/users
https://api.example.com/v2/users

Most visible and explicit
Easy for consumers to understand
Clear separation between versions
Can complicate routing

Header Versioning:

GET /users
API-Version: 2024-01-15

Cleaner URLs
More flexible for fine-grained versioning
Less obvious to consumers
Can use date-based or numeric versions

Query Parameter Versioning:

https://api.example.com/users?version=2

Simple to implement
Can interfere with caching
Generally considered less elegant

5.2 Version Lifecycle

Multi-Version API Architecture
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
// Supporting multiple API versions simultaneously
 
interface VersionConfig {
    version: string;
    status: 'current' | 'supported' | 'deprecated' | 'sunset';
    launchDate: Date;
    deprecationDate?: Date;
    sunsetDate?: Date;
    supportLevel: 'full' | 'security-only' | 'none';
}
 
const API_VERSIONS: VersionConfig[] = [
    {
        version: 'v3',
        status: 'current',
        launchDate: new Date('2024-01-15'),
        supportLevel: 'full',
    },
    {
        version: 'v2',
        status: 'supported', 
        launchDate: new Date('2022-06-01'),
        deprecationDate: new Date('2024-06-15'),
        sunsetDate: new Date('2025-06-15'),
        supportLevel: 'full',
    },
    {
        version: 'v1',
        status: 'deprecated',
        launchDate: new Date('2020-01-01'),
        deprecationDate: new Date('2022-01-01'),
        sunsetDate: new Date('2024-06-01'),
        supportLevel: 'security-only',
    },
];
 
// Version-aware routing
async function routeByVersion(req: Request): Promise<Response> {
    const version = extractVersion(req);
    const config = API_VERSIONS.find(v => v.version === version);
    
    if (!config) {
        return new Response(JSON.stringify({
            error: 'UNKNOWN_API_VERSION',
            message: `Version '${version}' is not recognized`,
            availableVersions: API_VERSIONS
                .filter(v => v.status !== 'sunset')
                .map(v => v.version),
        }), { status: 400 });
    }
    
    if (config.status === 'sunset') {
        return new Response(JSON.stringify({
            error: 'API_VERSION_SUNSET',
            message: `Version '${version}' was sunset on ${config.sunsetDate}`,
            migrationGuide: `https://docs.example.com/migrate-${version}`,
            currentVersion: 'v3',
        }), { status: 410 });  // 410 Gone
    }
    
    // Add deprecation headers for deprecated versions
    const headers = new Headers();
    if (config.status === 'deprecated') {
        headers.set('Deprecation', config.deprecationDate.toISOString());
        headers.set('Sunset', config.sunsetDate.toISOString());
        headers.set('Link', `<https://docs.example.com/migrate-${version}>; rel="successor-version"`);
    }
    
    // Route to version-specific handler
    const handler = versionHandlers[version];
    const response = await handler(req);
    
    // Add version info to response
    headers.set('API-Version', version);
    headers.set('API-Version-Status', config.status);
    
    return new Response(response.body, {
        status: response.status,
        headers: { ...Object.fromEntries(response.headers), ...Object.fromEntries(headers) },
    });
}

5.3 Version Coexistence

Maintaining multiple versions simultaneously is expensive but necessary:

Code organization options:

Separate codebases — Different services for each version
- Pro: Complete isolation
- Con: Duplicated effort for bugs/features in all versions
Version adapters — Single core with version-specific adapters
- Pro: Shared business logic
- Con: Adapter complexity grows over time
Feature flags — Single codebase with version-conditional behavior
- Pro: Simple for minor differences
- Con: Becomes spaghetti for major differences

New Version is a New Product

Each API version you maintain is effectively a separate product requiring support, testing, monitoring, and documentation. Limit the number of concurrent versions—ideally no more than 2-3. The maintenance burden grows faster than it appears.

The Deprecation Process

Deprecation is the formal process of winding down API support while giving consumers time to migrate.

6.1 When to Deprecate

Good reasons to deprecate:

New version provides better experience
Security vulnerabilities cannot be fixed
Underlying systems no longer supportable
Required by regulatory changes
Business pivot makes API non-strategic

Bad reasons to deprecate:

'Nobody uses it' (without data)
'It's old'
'We don't like the design'
'Maintaining it is annoying'

6.2 The Deprecation Timeline

Minimum deprecation period for external APIs: 12 months Recommended: 18-24 months

This timeline allows enterprise consumers—who may have annual budget cycles—to plan, budget, and execute migration projects.

Deprecation Communication Timeline
Timeframe	Action	Communication Channel
T-24 months	Announce new version availability	Blog, email, changelog
T-18 months	Announce deprecation date	Blog, email, in-API headers, changelog
T-12 months	Begin deprecation warnings in responses	API headers, dashboard notifications
T-6 months	Increase warning urgency	Direct email to high-volume users
T-3 months	Disable new API key creation for deprecated version	Dashboard, signup flow
T-1 month	Final migration reminder	Direct outreach to remaining users
T-1 week	Last call notification	All channels
T-0	Sunset: API returns 410 Gone	Status page, blog

Deprecation Headers (RFC 8594)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# Deprecation headers following IETF RFC 8594
 
# Standard deprecation header
Deprecation: Sat, 15 Jun 2024 00:00:00 GMT
 
# Sunset header with date API will be removed
Sunset: Sat, 15 Jun 2025 00:00:00 GMT
 
# Link header pointing to successor and documentation
Link: <https://api.example.com/v3/users>; rel="successor-version",
      <https://docs.example.com/deprecation-v2>; rel="deprecation"
 
# Example complete deprecated response:
 
HTTP/1.1 200 OK
Content-Type: application/json
API-Version: v2
API-Version-Status: deprecated
Deprecation: Sat, 15 Jun 2024 00:00:00 GMT
Sunset: Sat, 15 Jun 2025 00:00:00 GMT
Link: <https://api.example.com/v3/users>; rel="successor-version"
 
{
    "data": { ... },
    "warnings": [
        {
            "code": "API_VERSION_DEPRECATED",
            "message": "API version v2 is deprecated and will be sunset on 2025-06-15",
            "migrationGuide": "https://docs.example.com/migrate-v2-to-v3",
            "newVersionUrl": "https://api.example.com/v3"
        }
    ]
}

6.3 Migration Support

Deprecation is only ethical if you provide a migration path:

Essential migration resources:

Migration guide — Step-by-step instructions for every change
Comparison documentation — Old → new field/endpoint mapping
Coexistence period — Both versions work simultaneously
Testing tools — Help consumers verify their migration
Support channel — Dedicated support for migration issues

Migration assistance for large consumers:

Direct contact with dedicated support engineer
Custom migration timeline negotiation
Migration review sessions

Track Migration Progress

Monitor usage of deprecated versions/endpoints weekly. Identify consumers who aren't migrating and reach out proactively. Large consumers may not know about the deprecation—direct outreach often accelerates migration more than documentation.

Sunset Execution: Graceful Endings

The sunset phase is the final removal of API support. Done well, it's anticlimactic—everyone has migrated. Done poorly, it breaks production systems.

7.1 Pre-Sunset Checklist

Ready for Sunset?

•Usage at acceptable level — Less than X% of historic peak traffic
•All major consumers migrated — Directly confirmed with enterprise accounts
•Migration guide complete — No known gaps in documentation
•Support prepared — Team ready for surge in questions post-sunset
•Monitoring in place — Can see impact of sunset immediately
•Rollback plan — Can restore API access if critical issue discovered
•Communication complete — All channels notified, final reminder sent

7.2 Sunset Response

When a sunset API is called, return a helpful response:

Sunset Response Pattern
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 410 Gone
Content-Type: application/json
Sunset: Sat, 15 Jun 2024 00:00:00 GMT
 
{
    "error": {
        "code": "API_SUNSET",
        "message": "This API version (v1) was sunset on June 15, 2024",
        "details": "API version v1 is no longer available. Please migrate to v3.",
        "resources": {
            "migrationGuide": "https://docs.example.com/migrate-v1-to-v3",
            "currentApiDocs": "https://docs.example.com/v3",
            "support": "https://support.example.com/api-migration"
        },
        "timeline": {
            "deprecationAnnounced": "2022-06-15",
            "deprecationDate": "2023-01-15",
            "sunsetDate": "2024-06-15"
        }
    }
}

7.3 Post-Sunset Monitoring

After sunset, monitor for:

Error spikes in dependent services — Consumers may have missed dependencies
Support ticket volume — Be prepared for increase
Retry storms — Poorly-written clients may retry sunset endpoints aggressively

7.4 When to Grant Extensions

Sometimes, sunset must be delayed:

Consider extension if:

Critical customer cannot migrate in time due to regulatory freezes
Major bug in new version discovered near sunset
Acquisition/merger creates transition complexity

Do not extend for:

Consumer simply didn't prioritize migration
'We'll get to it soon'
Pressure without legitimate business reason

Extensions should be exception, not norm. Frequent extensions signal your deprecation timeline is too aggressive.

Clean Up After Sunset

After sunset stabilizes, remove the dead code. Sunset endpoints still running in prod create confusion and maintenance burden. Delete the code, remove the documentation, and close the chapter completely.

Lifecycle Governance

Effective API lifecycle management requires organizational governance—clear policies, assigned ownership, and systematic processes.

8.1 API Registry

Maintain a central registry of all APIs with lifecycle status:

API Registry Schema
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
interface ApiRegistryEntry {
    // Identification
    id: string;
    name: string;
    description: string;
    category: 'internal' | 'partner' | 'public';
    
    // Ownership
    owningTeam: string;
    technicalOwner: string;
    productOwner: string;
    
    // Lifecycle status
    status: 'design' | 'alpha' | 'beta' | 'ga' | 'deprecated' | 'sunset';
    statusChangedAt: Date;
    
    // Key dates
    designApprovedAt?: Date;
    alphaLaunchAt?: Date;
    betaLaunchAt?: Date;
    gaLaunchAt?: Date;
    deprecationAnnouncedAt?: Date;
    sunsetScheduledAt?: Date;
    sunsetCompletedAt?: Date;
    
    // Documentation
    specUrl: string;        // OpenAPI/GraphQL spec
    docsUrl: string;        // Human-readable docs
    changelogUrl: string;
    
    // Metrics
    lastWeekRequests: number;
    activeConsumers: number;
    errorRate: number;
    
    // Dependencies
    dependsOn: string[];        // APIs this API calls
    dependedOnBy: string[];     // APIs that call this API
    
    // Versioning
    currentVersion: string;
    supportedVersions: string[];
    deprecatedVersions: string[];
}
 
// Example registry entry:
const userApiEntry: ApiRegistryEntry = {
    id: 'api-user-service',
    name: 'User Service API',
    description: 'Core user management and authentication',
    category: 'public',
    
    owningTeam: 'identity-team',
    technicalOwner: 'jane.smith@company.com',
    productOwner: 'bob.jones@company.com',
    
    status: 'ga',
    statusChangedAt: new Date('2022-01-15'),
    
    gaLaunchAt: new Date('2022-01-15'),
    
    specUrl: 'https://specs.internal/user-api.yaml',
    docsUrl: 'https://docs.example.com/api/users',
    changelogUrl: 'https://docs.example.com/api/users/changelog',
    
    lastWeekRequests: 45_000_000,
    activeConsumers: 1_247,
    errorRate: 0.02,
    
    dependsOn: ['api-audit-service', 'api-notification-service'],
    dependedOnBy: ['api-order-service', 'api-billing-service', 'api-analytics-service'],
    
    currentVersion: 'v3',
    supportedVersions: ['v2', 'v3'],
    deprecatedVersions: ['v1'],
};

8.2 Lifecycle Review Process

Quarterly reviews for each API:

Is lifecycle status accurate?
Are deprecation timelines on track?
Are metrics healthy?
Are documentation and specs synchronized?
Any design review items from recent changes?

8.3 Ownership Model

Every API needs clear ownership:

Technical Owner: Engineer responsible for implementation, performance, reliability

Product Owner: PM responsible for roadmap, consumer needs, deprecation decisions

Executive Sponsor: Leader accountable for strategic alignment, resource allocation, cross-team coordination

Without clear ownership, APIs drift into neglect, documentation rots, and deprecations never complete.

API Gardening

Treat your API portfolio like a garden requiring continuous attention. Regular weeding (deprecation), fertilizing (documentation updates), and pruning (removing unused endpoints) keeps the garden healthy. Neglected gardens become overgrown and unusable.

Summary: Managing APIs Through Time

Understanding the API lifecycle transforms how you approach API design and maintenance. Let's consolidate the key insights:

Key Takeaways

•APIs are long-term commitments — Design decisions persist for years or decades; invest appropriately in design
•Lifecycle stages have different rules — What's acceptable in beta is forbidden in GA
•Backward compatibility is sacred — GA means no breaking changes outside versioning
•Versioning is expensive — Each version is a product to maintain; minimize concurrent versions
•Deprecation is a process, not a date — 12-24 months of communication, migration support, and monitoring
•Sunset requires preparation — Don't sunset until migration is complete for all consumers that matter
•Governance enables lifecycle management — API registry, ownership, regular reviews keep things healthy
•The time asymmetry — Months in design prevent decades of regret

Module Complete

You've now completed Module 1: What Is an API? You understand APIs as contracts, the internal/external distinction, API product thinking, and the full API lifecycle. This foundational knowledge prepares you for the next modules on specific API technologies: REST, GraphQL, gRPC, and beyond.

Module Complete

Congratulations on completing 'What Is an API?' You now have the conceptual foundation for API design—understanding APIs as contracts, products, and lifecycle-managed assets. The next module explores REST API design in depth, applying these foundational concepts to the most common API style.

4 / 4

Loading learning content...

System Design (HLD)What Is an API?

Understanding APIs: The Foundation of Modern System Communication

LevelBeginner

Duration60 mins

TopicWhat Is an API?

4 / 4

API Lifecycle

APIs Are Forever (Or Should Be)

Understanding the API lifecycle—from birth through evolution to eventual sunset—is essential for making decisions today that won't become regrets tomorrow.

What You Will Learn

The API Lifecycle Framework

APIs progress through well-defined lifecycle stages, each with distinct characteristics, objectives, and constraints.

1.1 The Five Stages

Stage 1: Design

Define the contract based on use cases
Make foundational decisions about style, naming, error handling
Review with stakeholders and potential consumers
Duration: Weeks to months

Stage 2: Preview (Alpha/Beta)

Expose to early adopters
Gather feedback and iterate
Breaking changes are permitted (with notice)
Duration: Months

Stage 3: General Availability (GA)

Production-ready for all consumers
Full support and SLA commitments
Breaking changes only through versioning
Duration: Years to decades

Stage 4: Deprecation

Announce intention to discontinue
Provide migration path to replacement
Maintain functionality but discourage new usage
Duration: 12-24+ months

Stage 5: Sunset/Retirement

Remove access to deprecated API
Complete migration of remaining consumers
Archive documentation
Duration: Final

Converting Mermaid diagram...

1.2 Stage Duration Expectations

Lifecycle stages have dramatically different durations:

API Lifecycle Stage Durations
Stage	Typical Duration	Key Milestone	Breaking Changes?
Design	2-6 months	Contract approval	N/A (not public)
Alpha	1-3 months	Internal testing complete	Yes, expected
Beta (Private)	2-6 months	Partner validation	Yes, with notice
Beta (Public)	1-3 months	Community feedback	Reluctantly, with notice
GA	5-20+ years	Full production launch	No (use versioning)
Deprecation	12-24+ months	Zero new integrations	No
Sunset	Single date	API shutdown	Total (API removed)

The Asymmetry of Time

The Design Phase: Decisions That Last

The design phase is where you make decisions that will persist for the lifetime of the API. Getting these right—or at least not catastrophically wrong—is critical.

2.1 Foundational Decisions

These decisions are nearly impossible to change after GA:

API Style and Protocol:

REST vs. GraphQL vs. gRPC vs. others
HTTP/1.1 vs. HTTP/2+ requirements
Streaming vs. request-response

Naming Conventions:

URL path structure (/users/123 vs /users/user_123)
Field naming (camelCase vs snake_case)
Terminology choices (what is a 'user' vs 'account' vs 'profile'?)

Authentication Model:

API keys vs. OAuth 2.0 vs. JWT
Header-based vs. query parameter vs. body
Scopes and permission model

Error Format:

Error structure (flat vs. nested)
Error codes (numeric vs. string)
Internationalization of error messages

Identifier Format:

UUID vs. sequential IDs vs. custom prefixed IDs
Opacity (can consumers infer meaning from IDs?)

Hard-to-Undo Design Decisions

•API style (REST → GraphQL)
•Authentication mechanism
•Base URL structure
•Resource naming/terminology
•ID format and opacity
•Error response structure
•Pagination approach
•Content-Type choices

Easier-to-Evolve Decisions

•Add new endpoints
•Add optional request parameters
•Add response fields
•Increase rate limits
•Add new enum values (with care)
•Add new authentication methods
•Add new SDK languages
•Improve error messages

2.2 Design Review Process

Robust design review prevents regrets:

API Design Review Checklist
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# API Design Review Checklist
 
## Pre-Review Requirements
- [ ] OpenAPI/GraphQL specification complete
- [ ] Example requests and responses for all operations
- [ ] Error cases documented
- [ ] Security model defined
- [ ] Rate limiting strategy defined
 
## Consistency Review
- [ ] Naming follows organizational conventions
- [ ] HTTP methods match operation semantics
- [ ] Response structures consistent with existing APIs
- [ ] Error format matches organizational standard
- [ ] Authentication consistent with other APIs
 
## Consumer Perspective Review
- [ ] Use cases clearly addressed
- [ ] Minimum viable operations included
- [ ] No leaky abstractions (internal details exposed)
- [ ] Sensible defaults for optional parameters
- [ ] Clear documentation for all fields
 
## Evolvability Review
- [ ] Room for future enhancements
- [ ] No unnecessary coupling to current implementation
- [ ] Pagination built in where lists may grow
- [ ] Versioning strategy defined
- [ ] Expansion patterns for response fields
 
## Security Review
- [ ] Authentication requirements appropriate
- [ ] Authorization model scalable
- [ ] Rate limiting prevents abuse
- [ ] No sensitive data in URLs or logs
- [ ] Input validation specified
 
## Operational Review
- [ ] Monitoring hooks defined
- [ ] SLA targets achievable
- [ ] Capacity planning complete
- [ ] Incident response plan
 
## Approval Gates
- [ ] API Product Manager approval
- [ ] Security team approval
- [ ] Documentation team review
- [ ] Consumer representative review (if known)

Prototype with Consumers

Preview Phase: Learning Through Exposure

The preview phase bridges design and GA. It's your last opportunity to make breaking changes without major coordination costs.

3.1 Alpha vs. Beta

Alpha:

Very early, may be unstable
Internal testing focus
Breaking changes expected weekly
No external commitments
Feature completeness: ~60-80%

Beta:

Feature complete (or nearly so)
External early adopters invited
Breaking changes possible but documented
Beginning to form external commitments
Feature completeness: ~90-100%

3.2 Setting Expectations

Clear communication prevents frustration:

Preview API Communication
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
HTTP/1.1 200 OK
Content-Type: application/json
X-API-Status: beta
X-API-Stability: experimental
X-API-Breaking-Change-Notice: This API is in beta. Breaking changes
    may occur with 2 weeks notice. Subscribe to changelog for updates.
 
{
    "data": { ... },
    "_meta": {
        "apiStatus": "beta",
        "stabilityLevel": "experimental",
        "breakingChangePolicy": "2 weeks notice via changelog",
        "changelogUrl": "https://changelog.example.com/beta-api",
        "feedbackEmail": "api-beta@example.com"
    }
}

3.3 Feedback Collection

The preview phase's primary value is learning. Active feedback collection is essential:

Quantitative feedback:

API usage patterns (which endpoints, frequencies)
Error rates by endpoint and error type
Latency distributions
Funnel metrics (signup → first call → production)

Qualitative feedback:

Developer interviews (what was hard?)
Support tickets (what confuses people?)
Community questions (what's unclear?)
Integration reviews (how did code turn out?)

3.4 When to Move to GA

GA Readiness Criteria

•Stability demonstrated — No breaking changes for 4+ weeks
•Performance validated — Latency and throughput meet targets at scale
•Error rates acceptable — 5xx errors < 0.1%
•Documentation complete — Full API reference, guides, examples
•SDKs ready — Official SDKs for major languages tested
•Support structure — Support channels operational
•SLA defined — Uptime and response time commitments ready
•Monitoring complete — Dashboards and alerts operational
•Consumer validation — At least 3 consumers in production successfully

Don't Rush to GA

General Availability: The Long Commitment

General Availability (GA) is a commitment. When you declare an API GA, you're promising:

Stability: No breaking changes without versioning
Support: Production-level support and SLAs
Longevity: Years of continued availability

4.1 What GA Means

GA is NOT:

Just removing the 'beta' label
A marketing milestone
The end of development

GA IS:

A contractual commitment to stability
The beginning of long-term maintenance
Elevated operational requirements
Restricted change flexibility

4.2 Backward Compatibility Promise

The core GA promise is backward compatibility: existing integrations continue to work. This means:

Backward Compatible vs. Breaking Changes
Change Type	Example	Compatible?
Add optional field to request	Add `metadata` object to POST body	✅ Yes
Add field to response	Add `createdAt` to user object	✅ Yes
Add new endpoint	Add `GET /users/{id}/preferences`	✅ Yes
Add new HTTP method	Add `PATCH /users/{id}`	✅ Yes
Widen accepted values	Accept both 'USD' and 'usd'	✅ Yes
Remove field from request	Remove `name` requirement	⚠️ Usually (test)
Remove field from response	Remove `legacyStatus`	❌ Breaking
Rename field	Rename `user_id` to `userId`	❌ Breaking
Change field type	Change `age` from string to int	❌ Breaking
Add required field	Require `email` on all requests	❌ Breaking
Remove endpoint	Remove `DELETE /deprecated`	❌ Breaking
Change error format	Change error structure	❌ Breaking
Stricter validation	Reject previously accepted values	❌ Breaking

Additive Evolution Pattern
1
2
3
4
5
6
7
// Original GA response (2020)
{
    "id": "usr_123",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "status": "active"
}

The Robustness Principle

Versioning Strategies for Breaking Changes

When breaking changes are unavoidable, versioning allows them without disrupting existing consumers.

5.1 Versioning Approaches

URL Path Versioning:

https://api.example.com/v1/users
https://api.example.com/v2/users

Most visible and explicit
Easy for consumers to understand
Clear separation between versions
Can complicate routing

Header Versioning:

GET /users
API-Version: 2024-01-15

Cleaner URLs
More flexible for fine-grained versioning
Less obvious to consumers
Can use date-based or numeric versions

Query Parameter Versioning:

https://api.example.com/users?version=2

Simple to implement
Can interfere with caching
Generally considered less elegant

5.2 Version Lifecycle

Multi-Version API Architecture
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
// Supporting multiple API versions simultaneously
 
interface VersionConfig {
    version: string;
    status: 'current' | 'supported' | 'deprecated' | 'sunset';
    launchDate: Date;
    deprecationDate?: Date;
    sunsetDate?: Date;
    supportLevel: 'full' | 'security-only' | 'none';
}
 
const API_VERSIONS: VersionConfig[] = [
    {
        version: 'v3',
        status: 'current',
        launchDate: new Date('2024-01-15'),
        supportLevel: 'full',
    },
    {
        version: 'v2',
        status: 'supported', 
        launchDate: new Date('2022-06-01'),
        deprecationDate: new Date('2024-06-15'),
        sunsetDate: new Date('2025-06-15'),
        supportLevel: 'full',
    },
    {
        version: 'v1',
        status: 'deprecated',
        launchDate: new Date('2020-01-01'),
        deprecationDate: new Date('2022-01-01'),
        sunsetDate: new Date('2024-06-01'),
        supportLevel: 'security-only',
    },
];
 
// Version-aware routing
async function routeByVersion(req: Request): Promise<Response> {
    const version = extractVersion(req);
    const config = API_VERSIONS.find(v => v.version === version);
    
    if (!config) {
        return new Response(JSON.stringify({
            error: 'UNKNOWN_API_VERSION',
            message: `Version '${version}' is not recognized`,
            availableVersions: API_VERSIONS
                .filter(v => v.status !== 'sunset')
                .map(v => v.version),
        }), { status: 400 });
    }
    
    if (config.status === 'sunset') {
        return new Response(JSON.stringify({
            error: 'API_VERSION_SUNSET',
            message: `Version '${version}' was sunset on ${config.sunsetDate}`,
            migrationGuide: `https://docs.example.com/migrate-${version}`,
            currentVersion: 'v3',
        }), { status: 410 });  // 410 Gone
    }
    
    // Add deprecation headers for deprecated versions
    const headers = new Headers();
    if (config.status === 'deprecated') {
        headers.set('Deprecation', config.deprecationDate.toISOString());
        headers.set('Sunset', config.sunsetDate.toISOString());
        headers.set('Link', `<https://docs.example.com/migrate-${version}>; rel="successor-version"`);
    }
    
    // Route to version-specific handler
    const handler = versionHandlers[version];
    const response = await handler(req);
    
    // Add version info to response
    headers.set('API-Version', version);
    headers.set('API-Version-Status', config.status);
    
    return new Response(response.body, {
        status: response.status,
        headers: { ...Object.fromEntries(response.headers), ...Object.fromEntries(headers) },
    });
}

5.3 Version Coexistence

Maintaining multiple versions simultaneously is expensive but necessary:

Code organization options:

Separate codebases — Different services for each version
- Pro: Complete isolation
- Con: Duplicated effort for bugs/features in all versions
Version adapters — Single core with version-specific adapters
- Pro: Shared business logic
- Con: Adapter complexity grows over time
Feature flags — Single codebase with version-conditional behavior
- Pro: Simple for minor differences
- Con: Becomes spaghetti for major differences

New Version is a New Product

The Deprecation Process

Deprecation is the formal process of winding down API support while giving consumers time to migrate.

6.1 When to Deprecate

Good reasons to deprecate:

New version provides better experience
Security vulnerabilities cannot be fixed
Underlying systems no longer supportable
Required by regulatory changes
Business pivot makes API non-strategic

Bad reasons to deprecate:

'Nobody uses it' (without data)
'It's old'
'We don't like the design'
'Maintaining it is annoying'

6.2 The Deprecation Timeline

Minimum deprecation period for external APIs: 12 months Recommended: 18-24 months

This timeline allows enterprise consumers—who may have annual budget cycles—to plan, budget, and execute migration projects.

Deprecation Communication Timeline
Timeframe	Action	Communication Channel
T-24 months	Announce new version availability	Blog, email, changelog
T-18 months	Announce deprecation date	Blog, email, in-API headers, changelog
T-12 months	Begin deprecation warnings in responses	API headers, dashboard notifications
T-6 months	Increase warning urgency	Direct email to high-volume users
T-3 months	Disable new API key creation for deprecated version	Dashboard, signup flow
T-1 month	Final migration reminder	Direct outreach to remaining users
T-1 week	Last call notification	All channels
T-0	Sunset: API returns 410 Gone	Status page, blog

Deprecation Headers (RFC 8594)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# Deprecation headers following IETF RFC 8594
 
# Standard deprecation header
Deprecation: Sat, 15 Jun 2024 00:00:00 GMT
 
# Sunset header with date API will be removed
Sunset: Sat, 15 Jun 2025 00:00:00 GMT
 
# Link header pointing to successor and documentation
Link: <https://api.example.com/v3/users>; rel="successor-version",
      <https://docs.example.com/deprecation-v2>; rel="deprecation"
 
# Example complete deprecated response:
 
HTTP/1.1 200 OK
Content-Type: application/json
API-Version: v2
API-Version-Status: deprecated
Deprecation: Sat, 15 Jun 2024 00:00:00 GMT
Sunset: Sat, 15 Jun 2025 00:00:00 GMT
Link: <https://api.example.com/v3/users>; rel="successor-version"
 
{
    "data": { ... },
    "warnings": [
        {
            "code": "API_VERSION_DEPRECATED",
            "message": "API version v2 is deprecated and will be sunset on 2025-06-15",
            "migrationGuide": "https://docs.example.com/migrate-v2-to-v3",
            "newVersionUrl": "https://api.example.com/v3"
        }
    ]
}

6.3 Migration Support

Deprecation is only ethical if you provide a migration path:

Essential migration resources:

Migration guide — Step-by-step instructions for every change
Comparison documentation — Old → new field/endpoint mapping
Coexistence period — Both versions work simultaneously
Testing tools — Help consumers verify their migration
Support channel — Dedicated support for migration issues

Migration assistance for large consumers:

Direct contact with dedicated support engineer
Custom migration timeline negotiation
Migration review sessions

Track Migration Progress

Sunset Execution: Graceful Endings

The sunset phase is the final removal of API support. Done well, it's anticlimactic—everyone has migrated. Done poorly, it breaks production systems.

7.1 Pre-Sunset Checklist

Ready for Sunset?

•Usage at acceptable level — Less than X% of historic peak traffic
•All major consumers migrated — Directly confirmed with enterprise accounts
•Migration guide complete — No known gaps in documentation
•Support prepared — Team ready for surge in questions post-sunset
•Monitoring in place — Can see impact of sunset immediately
•Rollback plan — Can restore API access if critical issue discovered
•Communication complete — All channels notified, final reminder sent

7.2 Sunset Response

When a sunset API is called, return a helpful response:

Sunset Response Pattern
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 410 Gone
Content-Type: application/json
Sunset: Sat, 15 Jun 2024 00:00:00 GMT
 
{
    "error": {
        "code": "API_SUNSET",
        "message": "This API version (v1) was sunset on June 15, 2024",
        "details": "API version v1 is no longer available. Please migrate to v3.",
        "resources": {
            "migrationGuide": "https://docs.example.com/migrate-v1-to-v3",
            "currentApiDocs": "https://docs.example.com/v3",
            "support": "https://support.example.com/api-migration"
        },
        "timeline": {
            "deprecationAnnounced": "2022-06-15",
            "deprecationDate": "2023-01-15",
            "sunsetDate": "2024-06-15"
        }
    }
}

7.3 Post-Sunset Monitoring

After sunset, monitor for:

Error spikes in dependent services — Consumers may have missed dependencies
Support ticket volume — Be prepared for increase
Retry storms — Poorly-written clients may retry sunset endpoints aggressively

7.4 When to Grant Extensions

Sometimes, sunset must be delayed:

Consider extension if:

Critical customer cannot migrate in time due to regulatory freezes
Major bug in new version discovered near sunset
Acquisition/merger creates transition complexity

Do not extend for:

Consumer simply didn't prioritize migration
'We'll get to it soon'
Pressure without legitimate business reason

Extensions should be exception, not norm. Frequent extensions signal your deprecation timeline is too aggressive.

Clean Up After Sunset

Lifecycle Governance

Effective API lifecycle management requires organizational governance—clear policies, assigned ownership, and systematic processes.

8.1 API Registry

Maintain a central registry of all APIs with lifecycle status:

API Registry Schema
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
interface ApiRegistryEntry {
    // Identification
    id: string;
    name: string;
    description: string;
    category: 'internal' | 'partner' | 'public';
    
    // Ownership
    owningTeam: string;
    technicalOwner: string;
    productOwner: string;
    
    // Lifecycle status
    status: 'design' | 'alpha' | 'beta' | 'ga' | 'deprecated' | 'sunset';
    statusChangedAt: Date;
    
    // Key dates
    designApprovedAt?: Date;
    alphaLaunchAt?: Date;
    betaLaunchAt?: Date;
    gaLaunchAt?: Date;
    deprecationAnnouncedAt?: Date;
    sunsetScheduledAt?: Date;
    sunsetCompletedAt?: Date;
    
    // Documentation
    specUrl: string;        // OpenAPI/GraphQL spec
    docsUrl: string;        // Human-readable docs
    changelogUrl: string;
    
    // Metrics
    lastWeekRequests: number;
    activeConsumers: number;
    errorRate: number;
    
    // Dependencies
    dependsOn: string[];        // APIs this API calls
    dependedOnBy: string[];     // APIs that call this API
    
    // Versioning
    currentVersion: string;
    supportedVersions: string[];
    deprecatedVersions: string[];
}
 
// Example registry entry:
const userApiEntry: ApiRegistryEntry = {
    id: 'api-user-service',
    name: 'User Service API',
    description: 'Core user management and authentication',
    category: 'public',
    
    owningTeam: 'identity-team',
    technicalOwner: 'jane.smith@company.com',
    productOwner: 'bob.jones@company.com',
    
    status: 'ga',
    statusChangedAt: new Date('2022-01-15'),
    
    gaLaunchAt: new Date('2022-01-15'),
    
    specUrl: 'https://specs.internal/user-api.yaml',
    docsUrl: 'https://docs.example.com/api/users',
    changelogUrl: 'https://docs.example.com/api/users/changelog',
    
    lastWeekRequests: 45_000_000,
    activeConsumers: 1_247,
    errorRate: 0.02,
    
    dependsOn: ['api-audit-service', 'api-notification-service'],
    dependedOnBy: ['api-order-service', 'api-billing-service', 'api-analytics-service'],
    
    currentVersion: 'v3',
    supportedVersions: ['v2', 'v3'],
    deprecatedVersions: ['v1'],
};

8.2 Lifecycle Review Process

Quarterly reviews for each API:

Is lifecycle status accurate?
Are deprecation timelines on track?
Are metrics healthy?
Are documentation and specs synchronized?
Any design review items from recent changes?

8.3 Ownership Model

Every API needs clear ownership:

Technical Owner: Engineer responsible for implementation, performance, reliability

Product Owner: PM responsible for roadmap, consumer needs, deprecation decisions

Executive Sponsor: Leader accountable for strategic alignment, resource allocation, cross-team coordination

Without clear ownership, APIs drift into neglect, documentation rots, and deprecations never complete.

API Gardening

Summary: Managing APIs Through Time

Understanding the API lifecycle transforms how you approach API design and maintenance. Let's consolidate the key insights:

Key Takeaways

•APIs are long-term commitments — Design decisions persist for years or decades; invest appropriately in design
•Lifecycle stages have different rules — What's acceptable in beta is forbidden in GA
•Backward compatibility is sacred — GA means no breaking changes outside versioning
•Versioning is expensive — Each version is a product to maintain; minimize concurrent versions
•Deprecation is a process, not a date — 12-24 months of communication, migration support, and monitoring
•Sunset requires preparation — Don't sunset until migration is complete for all consumers that matter
•Governance enables lifecycle management — API registry, ownership, regular reviews keep things healthy
•The time asymmetry — Months in design prevent decades of regret

Module Complete

Module Complete

4 / 4