System Design (HLD)What Is an API?

Understanding APIs: The Foundation of Modern System Communication

LevelBeginner

Duration60 mins

TopicWhat Is an API?

2 / 4

Internal vs External APIs

Two Audiences, Two Worlds

When Netflix engineers build APIs for their mobile apps to fetch movie recommendations, they face fundamentally different constraints than when they build APIs for internal services to communicate about user preferences. Both are APIs. Both follow similar technical patterns. Yet the design decisions, security models, versioning strategies, and operational requirements diverge dramatically.

The distinction between internal APIs (consumed within your organization) and external APIs (consumed by third parties) is one of the most consequential architectural decisions in API design. Getting this classification wrong leads to either over-engineered internal APIs that slow development velocity, or under-protected external APIs that create security vulnerabilities and break partner integrations.

This page provides a rigorous framework for understanding these two API categories, their unique requirements, and how to design appropriately for each.

What You Will Learn

You will understand the fundamental differences between internal and external APIs across dimensions including: trust models, security requirements, versioning constraints, documentation standards, SLA expectations, and governance approaches. You'll learn when to apply which set of constraints and how to design APIs that serve their intended audience effectively.

Defining Internal and External APIs

Before diving into differences, we need precise definitions. The internal/external distinction isn't always as simple as 'inside the company' versus 'outside.'

1.1 Internal APIs (Private APIs)

Internal APIs are consumed exclusively by systems and teams within the same organization. They enable:

Service-to-service communication in microservice architectures
Backend-for-frontend patterns where web/mobile apps call internal services
Data sharing between teams (e.g., User Service exposing data to Billing Service)
Orchestration layers coordinating multiple internal services

Key characteristics:

Consumers are employees or systems you control
You can communicate directly with all consumers
Breaking changes can be coordinated internally
Source code and implementation details are accessible
Network traffic stays within trusted boundaries

1.2 External APIs (Public APIs / Partner APIs)

External APIs are consumed by parties outside your organization. They subdivide into:

Public APIs — Available to any developer

Stripe's payment API
GitHub's repository API
Google Maps API
Twitter/X API

Partner APIs — Available to specific business partners

APIs shared between companies in a supply chain
White-label product APIs for resellers
B2B integration APIs for enterprise customers

Key characteristics:

Consumers are unknown developers or third-party systems
You cannot directly communicate with all consumers
Breaking changes cause external coordination overhead
Implementation details must be hidden
Network traffic crosses trust boundaries

Internal vs External API Characteristics
Characteristic	Internal APIs	External APIs
Consumer identity	Known employees/systems	Unknown developers/companies
Communication channel	Direct (Slack, meetings)	Indirect (docs, support tickets)
Trust level	High (same org)	Low (untrusted by default)
Breaking change cost	Coordination within org	Unknown cascade effects
Implementation visibility	Source code accessible	Black box to consumers
Usage control	Can enforce policies	Can only suggest patterns

The Developer Portal Test

Quick heuristic: If you need a developer portal for consumer self-service, you're building an external API. If you can just ping the consuming team on Slack when something changes, you might be building an internal API. This isn't definitive, but it helps identify which category your API falls into.

Security Models

Security is the dimension where internal and external APIs diverge most dramatically. The fundamental difference lies in the trust model.

2.1 Internal API Security: Trust but Verify

Internal APIs operate within a trusted network perimeter (or zero-trust mesh). Key security patterns:

Service-to-Service Authentication:

mTLS (mutual TLS) between services
Service mesh identity (Istio, Linkerd)
Internal JWTs issued by identity service
Kubernetes service accounts

Authorization:

Often implicit based on service identity
RBAC at the service level
Less granular than external APIs

Network Security:

Private network segments
Firewall rules restricting access
Service mesh encryption

2.2 External API Security: Trust Nothing

External APIs must assume hostile consumers. Every request could be an attack:

Security Strategy Comparison
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
// Internal API: Trust within network boundary
// Lighter security, relies on network isolation
 
import { FastifyRequest, FastifyReply } from 'fastify';
 
// Internal service-to-service authentication
async function internalAuthMiddleware(
    request: FastifyRequest,
    reply: FastifyReply
) {
    // Verify mTLS client certificate (handled by service mesh)
    const serviceIdentity = request.headers['x-forwarded-client-cert'];
    
    if (!serviceIdentity) {
        // If no mTLS, fall back to internal JWT
        const internalToken = request.headers['x-internal-service-token'];
        
        if (!verifyInternalToken(internalToken)) {
            return reply.status(401).send({ 
                error: 'Invalid service identity' 
            });
        }
    }
    
    // Authorization is simpler - service X can call service Y
    // Often implicit based on network topology
    const callingService = extractServiceName(serviceIdentity);
    request.callingService = callingService;
    
    // Log for audit but don't add heavy overhead
    request.log.debug({ 
        caller: callingService, 
        endpoint: request.url 
    });
}
 
// Less aggressive rate limiting for internal services
const internalRateLimits = {
    max: 10000,        // High limits for trusted services
    timeWindow: '1m',
    keyGenerator: (req) => req.callingService,  // Per-service limits
};

2.3 Security Comparison Matrix

Security Requirements by API Type
Security Measure	Internal APIs	External APIs
Authentication	mTLS, service mesh, internal JWT	API keys, OAuth 2.0, JWT
Authorization	Service-level, coarse-grained	User-level, fine-grained scopes
Rate limiting	High limits, per-service	Low limits, per-key/user
Input validation	Trust service contracts	Validate everything, trust nothing
Encryption	Service mesh (often transparent)	TLS required, pinning recommended
Audit logging	Operational focus	Compliance + security focus
Abuse detection	Anomaly monitoring	Active threat detection + blocking
Error messages	Can include details	Sanitized, no internal info

Never Expose Internal APIs Externally

A common security vulnerability is accidentally exposing internal APIs to external networks. Internal APIs lack the defensive depth required for hostile environments. Use network segmentation, API gateways, and regular security audits to ensure internal APIs remain internal.

Versioning Strategies

API versioning requirements differ dramatically based on consumer accessibility. This is where the true cost of external APIs becomes apparent.

3.1 Internal API Versioning: Move Fast

Internal APIs can use aggressive versioning because:

You control all consumers
You can coordinate upgrades directly
You can deploy changes simultaneously across services
Breaking changes can be announced in team channels

Common internal versioning approaches:

No explicit versioning — Just change the API and update all consumers in the same deployment. Works in monorepos with shared deployment.

Date-based versioning — api-2024-01-15 for internal documentation. Change freely, document what changed.

Feature flags — Toggle new behavior for internal testing before making it default.

3.2 External API Versioning: Move Carefully

External APIs require conservative versioning because:

You cannot force consumer upgrades
Consumers may have months of budget cycles before they can upgrade
Breaking changes destroy trust and partnership value
You have no visibility into how consumers use your API

Essential external versioning principles:

External API Versioning Rules

•Explicit version in URL or header — api.example.com/v1/ or API-Version: 2024-01-15
•Multi-version support — Run v1 and v2 simultaneously for 12-24 months
•Deprecation notices — Months of warning before any removal
•Backward compatibility by default — Additive changes only within a version
•Semantic versioning for SDKs — Help consumers understand change impact
•Migration guides — Detailed documentation for every version transition

External API Version Management
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
# OpenAPI specification with URL versioning
openapi: 3.0.0
info:
  title: External Payment API
  version: 2.0.0      # Semantic version of this spec
  description: |
    ## API Versioning
    This API uses URL path versioning.
    
    **Current version:** /v2
    **Supported versions:** /v1 (deprecated), /v2
    
    ### Version 1 Deprecation
    - **Deprecated:** January 1, 2024
    - **Sunset date:** July 1, 2024
    - **Migration guide:** https://docs.example.com/migrate-v1-v2
    
    ### Breaking Changes in v2
    - `amount` field changed from cents (integer) to Money object
    - `customer_id` renamed to `customerId` for consistency
    - Removed `charge` endpoint (use `payments` instead)
 
servers:
  - url: https://api.example.com/v2
    description: Production (current)
  - url: https://api.example.com/v1
    description: Production (deprecated - sunset July 2024)
 
paths:
  /payments:
    post:
      operationId: createPayment
      summary: Create a payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - customerId
              properties:
                amount:
                  $ref: '#/components/schemas/Money'  # v2: structured object
                customerId:
                  type: string
                  description: Customer identifier (renamed from customer_id in v1)

The Hyrum's Law Trap

Hyrum's Law states: 'With a sufficient number of users, every observable behavior of your API will be depended upon by someone.' For external APIs, this means even 'internal implementation details' that leak through responses become part of your de facto contract. Be extremely careful about what you expose.

Documentation Standards

Documentation requirements scale dramatically with API externality. The key insight is that internal teams have tacit knowledge that external developers lack.

4.1 Internal API Documentation

Internal documentation can be leaner because:

Developers can ask questions directly
Everyone understands domain context
Code is accessible as documentation
Tribal knowledge fills gaps

Minimum internal doc requirements:

OpenAPI spec (auto-generated acceptable)
Quick-start examples
Package/service README
Architecture decision records (ADRs)

4.2 External API Documentation

External documentation must be comprehensive and self-service:

Developers cannot ask clarifying questions easily
There's no shared context or domain knowledge
Code is not accessible
Support tickets are expensive

External documentation requirements:

External API Documentation Checklist

•Getting Started Guide — 5-minute integration to first successful call
•Authentication Guide — Step-by-step credential setup with screenshots
•API Reference — Complete specification for every endpoint
•Code Samples — In every major language (Node, Python, Go, Java, etc.)
•Interactive Explorer — Try-it-now functionality in docs
•Error Reference — Every error code with causes and solutions
•Rate Limit Documentation — Limits, headers, backoff strategies
•Webhook Documentation — Event types, payload schemas, verification
•Migration Guides — Detailed steps for version upgrades
•Use Case Guides — Common patterns with full examples
•SDKs and Libraries — Official clients for major platforms
•Changelog — Every change, categorized by impact
•Status Page — Real-time health and incident history
•FAQ and Troubleshooting — Common issues and solutions

Documentation Effort by API Type
Documentation Element	Internal API	External API
Time to maintain ratio	10% of dev time	30-50% of dev time
Languages covered	Company primary language	5-10 major languages
Update frequency	With releases	Continuous, real-time
Review process	Peer review	Technical writer + editorial
User feedback integration	Slack channel	Formal feedback loops
Versioning	Latest only	All supported versions

Documentation as Product

For external APIs, documentation IS part of the product. Poor documentation causes integration failures, increases support costs, and drives developers to competitors. Budget documentation effort into external API development from day one.

Operational Requirements

Operational expectations—SLAs, monitoring, and incident response—differ significantly between internal and external APIs.

5.1 Internal API Operations

Internal APIs operate under shared fate with their consumers:

If the User Service is down, the Order Service can't function anyway
SLAs are often implicit based on system requirements
Incidents are handled collaboratively across teams
Degradation can be communicated instantly

Typical internal API operational model:

Internal vs External SLA Definition
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
# Internal API Service Level Objectives (SLOs)
# These are targets, not contractual guarantees
 
service: user-service
slo:
  availability:
    target: 99.9%
    measurement_window: 30d
    # Note: No financial penalties, just engineering priority
    escalation:
      - threshold: 99.5%
        action: Slack alert to team
      - threshold: 99%
        action: Incident declared, cross-team sync
  
  latency:
    p50: 50ms
    p95: 200ms
    p99: 500ms
    # Measured at service mesh, not external
    
  error_rate:
    target: < 0.1%
    # Excludes 4xx client errors
 
monitoring:
  dashboards:
    - url: https://grafana.internal/user-service
  
  alerting:
    on_call: user-service-team
    slack: "#user-service-alerts"
    # No external status page needed

5.2 External API Operations: The Spotlight

External APIs operate under contractual obligations with real consequences:

Downtime means customer-facing failures for third parties
SLA breaches may trigger financial penalties
Incidents require external communication
Recovery must be faster than internal tolerance

5.3 Incident Response Comparison

Internal API Incident

•Alert fires to on-call team
•Slack thread in engineering channel
•Impacted teams notified directly
•Root cause shared in post-mortem
•Timeline: hours to days for RCA

External API Incident

•Alert fires with high priority
•Status page updated immediately
•Customer success and support alerted
•External communication drafted
•Executive notification if SLA at risk
•Post-incident review with customer sync
•Timeline: immediate updates required

External API Outage = Public Event

When external APIs fail, customers discover it through their own monitoring. Twitter fills with complaints. Support tickets spike. Unlike internal failures, you cannot control the narrative. This is why external APIs require redundancy, geographic distribution, and aggressive monitoring that internal APIs may not justify.

Governance and Review Processes

API governance—the policies and processes for API design, review, and evolution—must scale with API externality.

6.1 Internal API Governance

Internal APIs benefit from lightweight governance:

Team autonomy to design APIs for their services
Style guides rather than mandatory reviews
Automated linting rather than manual approval
Post-hoc review during code review

Appropriate internal governance:

Shared style guide (naming conventions, error formats)
Automated OpenAPI validation in CI
Service mesh policies for security baseline
Architecture review for new services (not every endpoint)

6.2 External API Governance

External APIs require formal governance because:

Changes persist indefinitely in the public sphere
Inconsistencies confuse external developers
Security flaws become attack vectors
Poor design reflects on company brand

External API governance requirements:

External API Review Checklist

•Design Review Board — Senior engineers approve all external API designs before implementation
•Security Review — Dedicated security review for authentication, authorization, input validation
•Legal Review — For APIs involving user data, PII, or regulated domains
•Documentation Review — Technical writer review before launch
•Consistency Audit — Verify alignment with existing API patterns
•Backward Compatibility Check — Automated verification that changes don't break clients
•Performance Testing — Load testing at 10x expected scale
•Deprecation Approval — Formal process for removing any external feature

Governance Intensity by API Type
Governance Element	Internal API	External API
Design approval	Team lead	API Review Board
Breaking changes	Coordinate with consumers	12+ month deprecation cycle
Naming conventions	Suggested style guide	Enforced standards
Security review	Automated scanning	Manual security audit
Documentation	Team responsibility	Technical writer required
Launch process	Feature flag rollout	Formal GA announcement

Governance as Investment

Heavy governance for external APIs isn't bureaucracy—it's investment protection. A poorly designed external API creates years of support burden, damages developer trust, and becomes permanent legacy. The upfront governance cost is 10x cheaper than fixing a public API mistake.

The Middle Ground: Partner APIs

Between fully internal and fully public APIs exists a spectrum of partner APIs with hybrid characteristics.

7.1 Partner API Characteristics

Partner APIs serve known external parties under negotiated terms:

Limited audience — Specific business partners, not the public
Known identity — You know who consumers are and can contact them
Negotiated terms — SLAs, limits, and access are per-partner
Shared responsibility — Partners may have integration support duties

7.2 When to Use Partner API Strategy

Good candidates for partner APIs:

B2B integrations with enterprise customers
Supply chain data exchange
White-label product APIs
Reseller platforms

When to avoid partner APIs (go public instead):

Self-service is feasible and desired
Many small integrators expected
Partner onboarding cost exceeds value

7.3 Partner API Design Considerations

Partner API Hybrid Approach
Dimension	Internal Approach	External Approach	Partner API Approach
Onboarding	Automatic access	Self-service portal	Sales-assisted, custom setup
Rate limits	High defaults	Fixed tiers	Negotiated per-partner
SLA	Implicit	Published tiers	Custom per agreement
Support	Slack/internal	Ticket-based	Dedicated account manager
Breaking changes	Coordinate	Long deprecation	Direct partner communication
Documentation	Internal docs	Public docs	Public + partner-specific guides
Versioning	Aggressive	Conservative	Partner-coordinated

Partner-Specific Configuration
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
// Partner API configuration management
// Each partner can have custom limits, features, and access
 
interface PartnerConfig {
    id: string;
    name: string;
    
    // Custom rate limits negotiated per contract
    rateLimits: {
        requestsPerMinute: number;
        requestsPerDay: number;
        burstAllowance: number;
    };
    
    // Feature flags for gradual rollout
    enabledFeatures: Set<string>;
    
    // API versions this partner has access to
    allowedVersions: string[];
    
    // Custom SLA tier
    slaTier: 'standard' | 'premium' | 'enterprise';
    
    // Support configuration
    support: {
        dedicatedContactEmail: string;
        slackChannel?: string;
        escalationPath: string[];
    };
    
    // Webhook configuration
    webhooks: {
        endpoints: string[];
        signingSecret: string;
        retryPolicy: 'standard' | 'aggressive';
    };
}
 
// Example partner configurations
const partnerConfigs: PartnerConfig[] = [
    {
        id: 'partner_acme_corp',
        name: 'ACME Corporation',
        rateLimits: {
            requestsPerMinute: 10000,  // 100x standard
            requestsPerDay: 5000000,
            burstAllowance: 1.5,
        },
        enabledFeatures: new Set([
            'beta-analytics-api',      // Early access
            'bulk-operations',         // Enterprise feature
            'custom-webhooks',
        ]),
        allowedVersions: ['2023-06-01', '2024-01-15'],
        slaTier: 'enterprise',
        support: {
            dedicatedContactEmail: 'acme-support@example.com',
            slackChannel: '#acme-integration',
            escalationPath: ['account-manager@example.com', 'cto@example.com'],
        },
        webhooks: {
            endpoints: ['https://acme.com/webhooks/example'],
            signingSecret: 'whsec_...',
            retryPolicy: 'aggressive',
        },
    },
];

Partner APIs as Stepping Stone

Many successful public APIs started as partner APIs. This path allows you to learn from a small group of sophisticated integrators before opening to the masses. Stripe, Twilio, and AWS all used early partner programs to refine their APIs before general availability.

Summary: Designing for Your Audience

The internal/external distinction fundamentally shapes every API design decision. Let's consolidate the key frameworks:

Key Takeaways

•Classification matters first — Determine if your API is internal, partner, or public before designing
•Trust models differ fundamentally — Internal assumes good faith; external assumes adversarial consumers
•Security scales with exposure — External APIs need defense-in-depth that internal APIs can skip
•Versioning cost increases externally — Breaking external changes cost 100x what internal changes cost
•Documentation is product for external — External APIs require comprehensive, self-service documentation
•Operations formalize externally — External APIs need SLAs, status pages, and incident communication
•Governance prevents regret — External API review processes prevent permanent public mistakes
•Partner APIs are valid middle ground — Hybrid approach when public is too much but internal is too little

What's next:

With the internal/external framework established, we'll explore APIs as products—how product thinking transforms API design from a technical exercise into a strategic business activity.

Page Complete

You now have a framework for classifying APIs and understanding how that classification changes design decisions. This framework will inform every subsequent topic—from REST design to versioning to gateway patterns. Keep asking 'internal or external?' as your first design question.

2 / 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?

2 / 4

Internal vs External APIs

Two Audiences, Two Worlds

This page provides a rigorous framework for understanding these two API categories, their unique requirements, and how to design appropriately for each.

What You Will Learn

Defining Internal and External APIs

Before diving into differences, we need precise definitions. The internal/external distinction isn't always as simple as 'inside the company' versus 'outside.'

1.1 Internal APIs (Private APIs)

Internal APIs are consumed exclusively by systems and teams within the same organization. They enable:

Service-to-service communication in microservice architectures
Backend-for-frontend patterns where web/mobile apps call internal services
Data sharing between teams (e.g., User Service exposing data to Billing Service)
Orchestration layers coordinating multiple internal services

Key characteristics:

Consumers are employees or systems you control
You can communicate directly with all consumers
Breaking changes can be coordinated internally
Source code and implementation details are accessible
Network traffic stays within trusted boundaries

1.2 External APIs (Public APIs / Partner APIs)

External APIs are consumed by parties outside your organization. They subdivide into:

Public APIs — Available to any developer

Stripe's payment API
GitHub's repository API
Google Maps API
Twitter/X API

Partner APIs — Available to specific business partners

APIs shared between companies in a supply chain
White-label product APIs for resellers
B2B integration APIs for enterprise customers

Key characteristics:

Consumers are unknown developers or third-party systems
You cannot directly communicate with all consumers
Breaking changes cause external coordination overhead
Implementation details must be hidden
Network traffic crosses trust boundaries

Internal vs External API Characteristics
Characteristic	Internal APIs	External APIs
Consumer identity	Known employees/systems	Unknown developers/companies
Communication channel	Direct (Slack, meetings)	Indirect (docs, support tickets)
Trust level	High (same org)	Low (untrusted by default)
Breaking change cost	Coordination within org	Unknown cascade effects
Implementation visibility	Source code accessible	Black box to consumers
Usage control	Can enforce policies	Can only suggest patterns

The Developer Portal Test

Security Models

Security is the dimension where internal and external APIs diverge most dramatically. The fundamental difference lies in the trust model.

2.1 Internal API Security: Trust but Verify

Internal APIs operate within a trusted network perimeter (or zero-trust mesh). Key security patterns:

Service-to-Service Authentication:

mTLS (mutual TLS) between services
Service mesh identity (Istio, Linkerd)
Internal JWTs issued by identity service
Kubernetes service accounts

Authorization:

Often implicit based on service identity
RBAC at the service level
Less granular than external APIs

Network Security:

Private network segments
Firewall rules restricting access
Service mesh encryption

2.2 External API Security: Trust Nothing

External APIs must assume hostile consumers. Every request could be an attack:

Security Strategy Comparison
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
// Internal API: Trust within network boundary
// Lighter security, relies on network isolation
 
import { FastifyRequest, FastifyReply } from 'fastify';
 
// Internal service-to-service authentication
async function internalAuthMiddleware(
    request: FastifyRequest,
    reply: FastifyReply
) {
    // Verify mTLS client certificate (handled by service mesh)
    const serviceIdentity = request.headers['x-forwarded-client-cert'];
    
    if (!serviceIdentity) {
        // If no mTLS, fall back to internal JWT
        const internalToken = request.headers['x-internal-service-token'];
        
        if (!verifyInternalToken(internalToken)) {
            return reply.status(401).send({ 
                error: 'Invalid service identity' 
            });
        }
    }
    
    // Authorization is simpler - service X can call service Y
    // Often implicit based on network topology
    const callingService = extractServiceName(serviceIdentity);
    request.callingService = callingService;
    
    // Log for audit but don't add heavy overhead
    request.log.debug({ 
        caller: callingService, 
        endpoint: request.url 
    });
}
 
// Less aggressive rate limiting for internal services
const internalRateLimits = {
    max: 10000,        // High limits for trusted services
    timeWindow: '1m',
    keyGenerator: (req) => req.callingService,  // Per-service limits
};

2.3 Security Comparison Matrix

Security Requirements by API Type
Security Measure	Internal APIs	External APIs
Authentication	mTLS, service mesh, internal JWT	API keys, OAuth 2.0, JWT
Authorization	Service-level, coarse-grained	User-level, fine-grained scopes
Rate limiting	High limits, per-service	Low limits, per-key/user
Input validation	Trust service contracts	Validate everything, trust nothing
Encryption	Service mesh (often transparent)	TLS required, pinning recommended
Audit logging	Operational focus	Compliance + security focus
Abuse detection	Anomaly monitoring	Active threat detection + blocking
Error messages	Can include details	Sanitized, no internal info

Never Expose Internal APIs Externally

Versioning Strategies

API versioning requirements differ dramatically based on consumer accessibility. This is where the true cost of external APIs becomes apparent.

3.1 Internal API Versioning: Move Fast

Internal APIs can use aggressive versioning because:

You control all consumers
You can coordinate upgrades directly
You can deploy changes simultaneously across services
Breaking changes can be announced in team channels

Common internal versioning approaches:

No explicit versioning — Just change the API and update all consumers in the same deployment. Works in monorepos with shared deployment.

Date-based versioning — api-2024-01-15 for internal documentation. Change freely, document what changed.

Feature flags — Toggle new behavior for internal testing before making it default.

3.2 External API Versioning: Move Carefully

External APIs require conservative versioning because:

You cannot force consumer upgrades
Consumers may have months of budget cycles before they can upgrade
Breaking changes destroy trust and partnership value
You have no visibility into how consumers use your API

Essential external versioning principles:

External API Versioning Rules

•Explicit version in URL or header — api.example.com/v1/ or API-Version: 2024-01-15
•Multi-version support — Run v1 and v2 simultaneously for 12-24 months
•Deprecation notices — Months of warning before any removal
•Backward compatibility by default — Additive changes only within a version
•Semantic versioning for SDKs — Help consumers understand change impact
•Migration guides — Detailed documentation for every version transition

External API Version Management
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
# OpenAPI specification with URL versioning
openapi: 3.0.0
info:
  title: External Payment API
  version: 2.0.0      # Semantic version of this spec
  description: |
    ## API Versioning
    This API uses URL path versioning.
    
    **Current version:** /v2
    **Supported versions:** /v1 (deprecated), /v2
    
    ### Version 1 Deprecation
    - **Deprecated:** January 1, 2024
    - **Sunset date:** July 1, 2024
    - **Migration guide:** https://docs.example.com/migrate-v1-v2
    
    ### Breaking Changes in v2
    - `amount` field changed from cents (integer) to Money object
    - `customer_id` renamed to `customerId` for consistency
    - Removed `charge` endpoint (use `payments` instead)
 
servers:
  - url: https://api.example.com/v2
    description: Production (current)
  - url: https://api.example.com/v1
    description: Production (deprecated - sunset July 2024)
 
paths:
  /payments:
    post:
      operationId: createPayment
      summary: Create a payment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - customerId
              properties:
                amount:
                  $ref: '#/components/schemas/Money'  # v2: structured object
                customerId:
                  type: string
                  description: Customer identifier (renamed from customer_id in v1)

The Hyrum's Law Trap

Documentation Standards

Documentation requirements scale dramatically with API externality. The key insight is that internal teams have tacit knowledge that external developers lack.

4.1 Internal API Documentation

Internal documentation can be leaner because:

Developers can ask questions directly
Everyone understands domain context
Code is accessible as documentation
Tribal knowledge fills gaps

Minimum internal doc requirements:

OpenAPI spec (auto-generated acceptable)
Quick-start examples
Package/service README
Architecture decision records (ADRs)

4.2 External API Documentation

External documentation must be comprehensive and self-service:

Developers cannot ask clarifying questions easily
There's no shared context or domain knowledge
Code is not accessible
Support tickets are expensive

External documentation requirements:

External API Documentation Checklist

•Getting Started Guide — 5-minute integration to first successful call
•Authentication Guide — Step-by-step credential setup with screenshots
•API Reference — Complete specification for every endpoint
•Code Samples — In every major language (Node, Python, Go, Java, etc.)
•Interactive Explorer — Try-it-now functionality in docs
•Error Reference — Every error code with causes and solutions
•Rate Limit Documentation — Limits, headers, backoff strategies
•Webhook Documentation — Event types, payload schemas, verification
•Migration Guides — Detailed steps for version upgrades
•Use Case Guides — Common patterns with full examples
•SDKs and Libraries — Official clients for major platforms
•Changelog — Every change, categorized by impact
•Status Page — Real-time health and incident history
•FAQ and Troubleshooting — Common issues and solutions

Documentation Effort by API Type
Documentation Element	Internal API	External API
Time to maintain ratio	10% of dev time	30-50% of dev time
Languages covered	Company primary language	5-10 major languages
Update frequency	With releases	Continuous, real-time
Review process	Peer review	Technical writer + editorial
User feedback integration	Slack channel	Formal feedback loops
Versioning	Latest only	All supported versions

Documentation as Product

Operational Requirements

Operational expectations—SLAs, monitoring, and incident response—differ significantly between internal and external APIs.

5.1 Internal API Operations

Internal APIs operate under shared fate with their consumers:

If the User Service is down, the Order Service can't function anyway
SLAs are often implicit based on system requirements
Incidents are handled collaboratively across teams
Degradation can be communicated instantly

Typical internal API operational model:

Internal vs External SLA Definition
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
# Internal API Service Level Objectives (SLOs)
# These are targets, not contractual guarantees
 
service: user-service
slo:
  availability:
    target: 99.9%
    measurement_window: 30d
    # Note: No financial penalties, just engineering priority
    escalation:
      - threshold: 99.5%
        action: Slack alert to team
      - threshold: 99%
        action: Incident declared, cross-team sync
  
  latency:
    p50: 50ms
    p95: 200ms
    p99: 500ms
    # Measured at service mesh, not external
    
  error_rate:
    target: < 0.1%
    # Excludes 4xx client errors
 
monitoring:
  dashboards:
    - url: https://grafana.internal/user-service
  
  alerting:
    on_call: user-service-team
    slack: "#user-service-alerts"
    # No external status page needed

5.2 External API Operations: The Spotlight

External APIs operate under contractual obligations with real consequences:

Downtime means customer-facing failures for third parties
SLA breaches may trigger financial penalties
Incidents require external communication
Recovery must be faster than internal tolerance

5.3 Incident Response Comparison

Internal API Incident

•Alert fires to on-call team
•Slack thread in engineering channel
•Impacted teams notified directly
•Root cause shared in post-mortem
•Timeline: hours to days for RCA

External API Incident

•Alert fires with high priority
•Status page updated immediately
•Customer success and support alerted
•External communication drafted
•Executive notification if SLA at risk
•Post-incident review with customer sync
•Timeline: immediate updates required

External API Outage = Public Event

Governance and Review Processes

API governance—the policies and processes for API design, review, and evolution—must scale with API externality.

6.1 Internal API Governance

Internal APIs benefit from lightweight governance:

Team autonomy to design APIs for their services
Style guides rather than mandatory reviews
Automated linting rather than manual approval
Post-hoc review during code review

Appropriate internal governance:

Shared style guide (naming conventions, error formats)
Automated OpenAPI validation in CI
Service mesh policies for security baseline
Architecture review for new services (not every endpoint)

6.2 External API Governance

External APIs require formal governance because:

Changes persist indefinitely in the public sphere
Inconsistencies confuse external developers
Security flaws become attack vectors
Poor design reflects on company brand

External API governance requirements:

External API Review Checklist

•Design Review Board — Senior engineers approve all external API designs before implementation
•Security Review — Dedicated security review for authentication, authorization, input validation
•Legal Review — For APIs involving user data, PII, or regulated domains
•Documentation Review — Technical writer review before launch
•Consistency Audit — Verify alignment with existing API patterns
•Backward Compatibility Check — Automated verification that changes don't break clients
•Performance Testing — Load testing at 10x expected scale
•Deprecation Approval — Formal process for removing any external feature

Governance Intensity by API Type
Governance Element	Internal API	External API
Design approval	Team lead	API Review Board
Breaking changes	Coordinate with consumers	12+ month deprecation cycle
Naming conventions	Suggested style guide	Enforced standards
Security review	Automated scanning	Manual security audit
Documentation	Team responsibility	Technical writer required
Launch process	Feature flag rollout	Formal GA announcement

Governance as Investment

The Middle Ground: Partner APIs

Between fully internal and fully public APIs exists a spectrum of partner APIs with hybrid characteristics.

7.1 Partner API Characteristics

Partner APIs serve known external parties under negotiated terms:

Limited audience — Specific business partners, not the public
Known identity — You know who consumers are and can contact them
Negotiated terms — SLAs, limits, and access are per-partner
Shared responsibility — Partners may have integration support duties

7.2 When to Use Partner API Strategy

Good candidates for partner APIs:

B2B integrations with enterprise customers
Supply chain data exchange
White-label product APIs
Reseller platforms

When to avoid partner APIs (go public instead):

Self-service is feasible and desired
Many small integrators expected
Partner onboarding cost exceeds value

7.3 Partner API Design Considerations

Partner API Hybrid Approach
Dimension	Internal Approach	External Approach	Partner API Approach
Onboarding	Automatic access	Self-service portal	Sales-assisted, custom setup
Rate limits	High defaults	Fixed tiers	Negotiated per-partner
SLA	Implicit	Published tiers	Custom per agreement
Support	Slack/internal	Ticket-based	Dedicated account manager
Breaking changes	Coordinate	Long deprecation	Direct partner communication
Documentation	Internal docs	Public docs	Public + partner-specific guides
Versioning	Aggressive	Conservative	Partner-coordinated

Partner-Specific Configuration
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
// Partner API configuration management
// Each partner can have custom limits, features, and access
 
interface PartnerConfig {
    id: string;
    name: string;
    
    // Custom rate limits negotiated per contract
    rateLimits: {
        requestsPerMinute: number;
        requestsPerDay: number;
        burstAllowance: number;
    };
    
    // Feature flags for gradual rollout
    enabledFeatures: Set<string>;
    
    // API versions this partner has access to
    allowedVersions: string[];
    
    // Custom SLA tier
    slaTier: 'standard' | 'premium' | 'enterprise';
    
    // Support configuration
    support: {
        dedicatedContactEmail: string;
        slackChannel?: string;
        escalationPath: string[];
    };
    
    // Webhook configuration
    webhooks: {
        endpoints: string[];
        signingSecret: string;
        retryPolicy: 'standard' | 'aggressive';
    };
}
 
// Example partner configurations
const partnerConfigs: PartnerConfig[] = [
    {
        id: 'partner_acme_corp',
        name: 'ACME Corporation',
        rateLimits: {
            requestsPerMinute: 10000,  // 100x standard
            requestsPerDay: 5000000,
            burstAllowance: 1.5,
        },
        enabledFeatures: new Set([
            'beta-analytics-api',      // Early access
            'bulk-operations',         // Enterprise feature
            'custom-webhooks',
        ]),
        allowedVersions: ['2023-06-01', '2024-01-15'],
        slaTier: 'enterprise',
        support: {
            dedicatedContactEmail: 'acme-support@example.com',
            slackChannel: '#acme-integration',
            escalationPath: ['account-manager@example.com', 'cto@example.com'],
        },
        webhooks: {
            endpoints: ['https://acme.com/webhooks/example'],
            signingSecret: 'whsec_...',
            retryPolicy: 'aggressive',
        },
    },
];

Partner APIs as Stepping Stone

Summary: Designing for Your Audience

The internal/external distinction fundamentally shapes every API design decision. Let's consolidate the key frameworks:

Key Takeaways

•Classification matters first — Determine if your API is internal, partner, or public before designing
•Trust models differ fundamentally — Internal assumes good faith; external assumes adversarial consumers
•Security scales with exposure — External APIs need defense-in-depth that internal APIs can skip
•Versioning cost increases externally — Breaking external changes cost 100x what internal changes cost
•Documentation is product for external — External APIs require comprehensive, self-service documentation
•Operations formalize externally — External APIs need SLAs, status pages, and incident communication
•Governance prevents regret — External API review processes prevent permanent public mistakes
•Partner APIs are valid middle ground — Hybrid approach when public is too much but internal is too little

What's next:

With the internal/external framework established, we'll explore APIs as products—how product thinking transforms API design from a technical exercise into a strategic business activity.

Page Complete

2 / 4