API Design — APIs and Protocols | OneNoughtOne

0/121

Computer NetworksAPIs and Protocols

APIs and Protocols

LevelIntermediate

Duration60 mins

TopicAPIs and Protocols

5 / 5

API Design

The Art and Science of API Design

Designing an API is like designing a language. You're creating the vocabulary, grammar, and conventions that developers will use to communicate with your service. A well-designed API feels intuitive—developers can guess how things work without reading documentation. A poorly designed API causes endless confusion, support requests, and integration failures. API design matters because: APIs are contracts : Once published, changes break clients. Good upfront design prevents painful migrations. APIs are interfaces : They're how developers experience your service. Poor APIs tarnish your product's reputation. APIs have long lifespans : Well-designed APIs serve for years or decades. Bad design becomes permanent technical debt. This page synthesizes everything we've learned into coherent design principles and practices. We'll explore how to create APIs that are intuitive, consistent, secure, and evolvable.

What You Will Learn

By the end of this page, you will understand RESTful design principles, resource modeling, naming conventions, versioning strategies, rate limiting approaches, API security best practices, and documentation standards. You'll have a comprehensive framework for designing world-class APIs.

RESTful Design Principles

REST (Representational State Transfer) isn't a protocol—it's an architectural style with guiding constraints. Understanding these constraints helps you design APIs that are scalable, cacheable, and maintainable. The REST Constraints:

REST Architectural Constraints

•Client-Server Separation: The client and server evolve independently. The server knows nothing about the client's UI; the client knows nothing about the server's data storage.
•Statelessness: Each request contains all information needed to process it. The server doesn't store client session state between requests. This enables horizontal scaling.
•Cacheability: Responses must be labeled as cacheable or non-cacheable. Proper caching reduces server load and improves performance.
•Uniform Interface: APIs use consistent, standardized conventions. Resources are identified by URIs; operations use standard HTTP methods.
•Layered System: The client can't tell if it's connected directly to the server or through intermediaries (load balancers, CDNs, proxies).
•Code on Demand (Optional): Servers can extend client functionality by transferring executable code (like JavaScript). Rarely used in APIs.

Resource-Oriented Thinking: REST centers on resources —the nouns of your API. A resource is any concept that can be addressed and manipulated: A user: /users/42 A collection of orders: /orders A user's orders: /users/42/orders A configuration setting: /settings/timezone Actions become HTTP verbs on resources:

Instead of This	Do This
POST /createUser	POST /users
GET /getUser?id=42	GET /users/42
POST /deleteUser/42	DELETE /users/42
POST /updateUserEmail	PATCH /users/42

This transformation from RPC-style (verb-focused) to REST-style (resource-focused) is fundamental to RESTful design.

The Richardson Maturity Model

Leonard Richardson proposed a maturity model for REST APIs: Level 0 (single URI, single method), Level 1 (multiple URIs for resources), Level 2 (HTTP verbs for operations), Level 3 (hypermedia controls). Most production APIs aim for Level 2; full Level 3 (HATEOAS) is rare but valuable.

Resource Modeling

Effective API design starts with thoughtful resource modeling —identifying what resources your API exposes and how they relate to each other. Identifying Resources: Resources typically correspond to domain entities, but not always 1-to-1 with database tables: Entity resources : Users, products, orders—things with identity Collection resources : Lists of entities (/users, /orders) Composite resources : Aggregations for convenience (/dashboard, /search-results) Action resources : When operations don't fit CRUD (/transfers, /exports)

Converting Mermaid diagram...

Nested vs. Top-Level Resources: Decide when resources should be nested under parents:

Approach	Example	When to Use
Nested	`/users/42/orders`	Orders tightly bound to users; always accessed in user context
Top-level	`/orders` with `?user_id=42`	Orders have independent identity; accessed without user context
Both	`/users/42/orders` AND `/orders/1001`	Convenience + direct access

Guidelines: Nest when the child doesn't make sense without the parent Limit nesting to 2-3 levels (/a/1/b/2/c/3 is too deep) Provide top-level access if resources have global identity

Resource Modeling Example

Text

E-commerce API Resource Model:
 
/products                     # All products
/products/{id}                # Single product
/products/{id}/reviews        # Product's reviews
/products/{id}/variants       # Product variants (sizes, colors)
 
/categories                   # All categories
/categories/{id}              # Single category
/categories/{id}/products     # Products in category
 
/users                        # All users
/users/{id}                   # Single user
/users/{id}/addresses         # User's addresses
/users/{id}/payment-methods   # User's payment methods
 
/orders                       # All orders (admin access)
/orders/{id}                  # Single order
/orders/{id}/items            # Order line items
/orders/{id}/shipments        # Order shipments
 
/carts                        # Shopping carts
/carts/{id}/items             # Items in cart
 
# Action-oriented resources (when CRUD doesn't fit)
/checkout                     # Convert cart to order
/password-reset               # Password reset flow
/search                       # Cross-resource search

Naming Conventions

Consistent naming is critical for API usability. Developers should be able to guess endpoint names based on patterns they've observed. URL Path Conventions:

URL Naming Best Practices
Rule	Good	Avoid
Use nouns, not verbs	/users, /products	/getUsers, /createProduct
Use plural nouns for collections	/users/42	/user/42
Use lowercase	/user-profiles	/userProfiles, /User_Profiles
Use hyphens for multi-word	/user-profiles	/user_profiles, /userprofiles
No file extensions	/users/42	/users/42.json
No trailing slashes	/users/42	/users/42/

Query Parameter Conventions: Query parameters should follow consistent patterns:

Query Parameter Patterns

HTTP

# Filtering: field name as parameter
GET /products?category=electronics&min_price=100&max_price=500
 
# Sorting: explicit sort parameter with optional order
GET /products?sort=price&order=asc
GET /products?sort=-price  # Prefix with - for descending
 
# Pagination: consistent naming
GET /products?page=2&per_page=20
GET /products?limit=20&offset=40
GET /products?cursor=abc123
 
# Field selection: explicit fields parameter
GET /users/42?fields=id,name,email
 
# Expansion: include related resources
GET /orders/1001?expand=customer,items
 
# Search: use 'q' for search query
GET /products?q=wireless+headphones

JSON Field Naming: Choose and consistently apply a case convention:

Case	Example	Common In
camelCase	`firstName`, `createdAt`	JavaScript ecosystems
snake_case	`first_name`, `created_at`	Ruby, Python ecosystems
kebab-case	`first-name`	Rare in JSON; conflicts with math operators

Recommendation: Match your primary consumer language. If most clients are JavaScript apps, use camelCase. If Python, use snake_case. The key is consistency —never mix cases within an API.

Date and Time Formats

Always use ISO 8601 for dates and times: 2024-01-15T10:30:00Z . Include timezone (preferably UTC with 'Z' suffix). Never use locale-specific formats like 'MM/DD/YYYY'. This eliminates parsing ambiguity across clients.

Versioning Strategies

APIs evolve over time. New features are added, bugs are fixed, and occasionally breaking changes are necessary. Versioning provides a mechanism to manage this evolution without disrupting existing clients. Versioning Approaches:

API Versioning Strategies
Strategy	Example	Pros	Cons
URL Path	/api/v2/users	Explicit, easy to see, cacheable	URL pollution, hard for client library migration
Query Parameter	/api/users?version=2	Non-breaking URL, easy to default	Less visible, can be forgotten
Header	Api-Version: 2	Clean URLs, flexible negotiation	Hidden, harder to test/debug
Content Negotiation	Accept: application/vnd.api.v2+json	RESTful, precise format control	Complex, verbose

URL Path Versioning (Most Common):

URL Path Versioning

HTTP

# Version in URL path - most common approach
GET https://api.example.com/v1/users/42
GET https://api.example.com/v2/users/42
 
# V2 might have different response structure:
# v1: {"id": 42, "name": "Alice", "email": "alice@example.com"}
# v2: {"id": 42, "account": {"email": "alice@example.com"}, "profile": {"name": "Alice"}}

Header-Based Versioning (Stripe's Approach):

Header-Based Versioning

HTTP

# Request with version header
GET /v1/customers/cus_123 HTTP/1.1
Host: api.stripe.com
Stripe-Version: 2024-01-15
 
# Response adapts to requested version
# If version not specified, uses account's default version

Versioning Best Practices

•Start with v1: Always version from the beginning, even before breaking changes occur
•Increment rarely: Break only when absolutely necessary; additive changes don't need new versions
•Support multiple versions: Maintain old versions for a generous period (12-24 months)
•Communicate deprecation: Announce deprecation timeline well in advance
•Provide migration guides: Document exactly what changed and how to upgrade
•Use semantic versioning internally: Even if only major versions are public, track minor/patch internally

Evolutionary Design

Good API design minimizes breaking changes. Add new fields (don't remove old ones). Add new endpoints (don't change existing behavior). If a field meaning changes, create a new field with a new name. Well-designed APIs can evolve for years without version bumps.

Rate Limiting

Rate limiting protects APIs from abuse, ensures fair resource distribution, and maintains service quality. Every public API needs rate limiting. Common Rate Limiting Algorithms:

Rate Limiting Algorithms
Algorithm	How It Works	Characteristics
Fixed Window	Count requests per fixed time window (e.g., per minute)	Simple but burst at window edges
Sliding Window	Count requests in rolling time window	Smoother but more complex
Token Bucket	Tokens refill at constant rate; requests consume tokens	Allows controlled bursts
Leaky Bucket	Requests enter bucket, drain at fixed rate	Constant output rate, smooths traffic

Rate Limit Headers: Always communicate rate limit status to clients:

Rate Limit Headers

HTTP

# Successful response with rate limit info
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1705312860
 
# Rate limit exceeded
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312860
Retry-After: 45
Content-Type: application/json
 
{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded the rate limit of 100 requests per minute.",
  "retry_after": 45
}

Rate Limiting Strategies

•Per-user limits: Different limits for authenticated users vs. API keys vs. anonymous
•Per-endpoint limits: Expensive operations (search, reports) have lower limits than CRUD
•Burst allowance: Allow short bursts above sustained rate for legitimate use patterns
•Tiered limits: Premium tiers get higher limits (monetization strategy)
•Graceful degradation: Return cached/degraded responses before returning 429

Client-Side Best Practices

Good API clients respect rate limits gracefully: Check remaining quota before making requests, implement exponential backoff on 429 responses, spread requests over time instead of bursting, and cache responses to reduce unnecessary calls.

Security Best Practices

API security is paramount. A security breach can compromise user data, damage reputation, and violate regulations. Security must be designed in from the start, not bolted on later. Transport Security:

Transport Layer Security

•HTTPS Only: Never support plain HTTP. Redirect HTTP to HTTPS or reject outright.
•TLS 1.2+: Disable older TLS/SSL versions with known vulnerabilities.
•HSTS: Send Strict-Transport-Security header to prevent downgrade attacks.
•Certificate Pinning: For mobile apps, pin expected certificates to prevent MITM.

Authentication Security:

Authentication Best Practices
Practice	Implementation
Use tokens, not passwords	Issue JWTs or opaque tokens; never transmit passwords repeatedly
Short token expiry	Access tokens: 15 min to 1 hour; use refresh tokens for longer sessions
Secure token storage	Client-side: secure storage, not localStorage; Server-side: encrypted, not logs
Token revocation	Maintain revocation list or use short-lived tokens
Scope limitation	Tokens should have minimal necessary permissions

Input Validation and Injection Prevention:

Security Validation

Text

VALIDATION CHECKLIST:
 
✓ Validate all input on the server (never trust client validation)
✓ Validate data types, lengths, formats, and ranges
✓ Use parameterized queries for database access (prevent SQL injection)
✓ Escape output for context (HTML, JSON, etc.)
✓ Validate Content-Type matches actual body format
✓ Limit request body size (prevent DoS)
✓ Validate file uploads (type, size, and scan for malware)
 
NEVER:
✗ Interpolate user input into SQL queries
✗ Execute user-provided code (eval)
✗ Include user input in system commands
✗ Trust client-reported Content-Type without validation

Authorization and Access Control:

Authorization Principles

•Default deny: No access unless explicitly granted
•Check every request: Don't rely on hidden URLs; verify authorization on each endpoint
•Object-level authorization: Verify user can access the specific resource, not just the resource type
•Function-level authorization: Verify user can perform the specific action
•Avoid IDOR: Insecure Direct Object References allow guessing resource IDs; verify ownership

OWASP API Security Top 10

The OWASP API Security Top 10 lists common API vulnerabilities: Broken Object Level Authorization, Broken Authentication, Excessive Data Exposure, Lack of Resources & Rate Limiting, Broken Function Level Authorization, Mass Assignment, Security Misconfiguration, Injection, Improper Assets Management, and Insufficient Logging & Monitoring. Study and test for these.

Documentation

An API is only as good as its documentation. Developers evaluate APIs by their docs before writing any code. Poor documentation is a dealbreaker. Documentation Components:

Essential Documentation Elements

•Getting Started Guide: Quick path to first successful API call (5-10 minutes)
•Authentication Guide: How to obtain and use credentials, with code examples
•API Reference: Complete endpoint documentation with parameters, responses, errors
•Tutorials: Step-by-step guides for common use cases
•Code Examples: Samples in popular languages (JavaScript, Python, Ruby, cURL)
•Changelog: What changed in each version, migration guides for breaking changes
•Status Page: Real-time API health and incident history
•SDKs and Libraries: Official client libraries with documentation

API Reference Best Practices: Each endpoint should document:

Endpoint Documentation Template
Markdown
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
## Create Order
 
Creates a new order for the authenticated user.
 
### Endpoint
 
```
POST /api/v2/orders
```
 
### Authentication
 
Requires Bearer token with `orders:write` scope.
 
### Request Body
 
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| items | array | Yes | Array of order items |
| items[].product_id | string | Yes | Product identifier |
| items[].quantity | integer | Yes | Quantity (1-99) |
| shipping_address_id | string | Yes | Address for delivery |
| notes | string | No | Order notes (max 500 chars) |
 
### Response
 
**201 Created**
```json
{
  "id": "ord_abc123",
  "status": "pending",
  "items": [...],
  "total": 99.99,
  "created_at": "2024-01-15T10:30:00Z"
}
```
 
### Errors
 
| Status | Code | Description |
|--------|------|-------------|
| 400 | invalid_request | Malformed request body |
| 401 | unauthorized | Invalid or missing token |
| 422 | validation_error | Request failed validation |
| 422 | insufficient_stock | Product out of stock |

Interactive Documentation

Modern APIs provide interactive documentation (Swagger UI, Redocly, Postman) where developers can explore endpoints and make real API calls without leaving the docs. This 'try it now' capability dramatically improves developer experience and reduces time to first successful integration.

Computer NetworksAPIs and Protocols

APIs and Protocols

LevelIntermediate

Duration60 mins

TopicAPIs and Protocols

5 / 5

API Design

The Art and Science of API Design

Designing an API is like designing a language. You're creating the vocabulary, grammar, and conventions that developers will use to communicate with your service. A well-designed API feels intuitive—developers can guess how things work without reading documentation. A poorly designed API causes endless confusion, support requests, and integration failures. API design matters because: APIs are contracts : Once published, changes break clients. Good upfront design prevents painful migrations. APIs are interfaces : They're how developers experience your service. Poor APIs tarnish your product's reputation. APIs have long lifespans : Well-designed APIs serve for years or decades. Bad design becomes permanent technical debt. This page synthesizes everything we've learned into coherent design principles and practices. We'll explore how to create APIs that are intuitive, consistent, secure, and evolvable.

What You Will Learn

By the end of this page, you will understand RESTful design principles, resource modeling, naming conventions, versioning strategies, rate limiting approaches, API security best practices, and documentation standards. You'll have a comprehensive framework for designing world-class APIs.

RESTful Design Principles

REST (Representational State Transfer) isn't a protocol—it's an architectural style with guiding constraints. Understanding these constraints helps you design APIs that are scalable, cacheable, and maintainable. The REST Constraints:

REST Architectural Constraints

•Client-Server Separation: The client and server evolve independently. The server knows nothing about the client's UI; the client knows nothing about the server's data storage.
•Statelessness: Each request contains all information needed to process it. The server doesn't store client session state between requests. This enables horizontal scaling.
•Cacheability: Responses must be labeled as cacheable or non-cacheable. Proper caching reduces server load and improves performance.
•Uniform Interface: APIs use consistent, standardized conventions. Resources are identified by URIs; operations use standard HTTP methods.
•Layered System: The client can't tell if it's connected directly to the server or through intermediaries (load balancers, CDNs, proxies).
•Code on Demand (Optional): Servers can extend client functionality by transferring executable code (like JavaScript). Rarely used in APIs.

Resource-Oriented Thinking: REST centers on resources —the nouns of your API. A resource is any concept that can be addressed and manipulated: A user: /users/42 A collection of orders: /orders A user's orders: /users/42/orders A configuration setting: /settings/timezone Actions become HTTP verbs on resources:

Instead of This	Do This
POST /createUser	POST /users
GET /getUser?id=42	GET /users/42
POST /deleteUser/42	DELETE /users/42
POST /updateUserEmail	PATCH /users/42

This transformation from RPC-style (verb-focused) to REST-style (resource-focused) is fundamental to RESTful design.

The Richardson Maturity Model

Leonard Richardson proposed a maturity model for REST APIs: Level 0 (single URI, single method), Level 1 (multiple URIs for resources), Level 2 (HTTP verbs for operations), Level 3 (hypermedia controls). Most production APIs aim for Level 2; full Level 3 (HATEOAS) is rare but valuable.

Resource Modeling

Effective API design starts with thoughtful resource modeling —identifying what resources your API exposes and how they relate to each other. Identifying Resources: Resources typically correspond to domain entities, but not always 1-to-1 with database tables: Entity resources : Users, products, orders—things with identity Collection resources : Lists of entities (/users, /orders) Composite resources : Aggregations for convenience (/dashboard, /search-results) Action resources : When operations don't fit CRUD (/transfers, /exports)

Converting Mermaid diagram...

Nested vs. Top-Level Resources: Decide when resources should be nested under parents:

Approach	Example	When to Use
Nested	`/users/42/orders`	Orders tightly bound to users; always accessed in user context
Top-level	`/orders` with `?user_id=42`	Orders have independent identity; accessed without user context
Both	`/users/42/orders` AND `/orders/1001`	Convenience + direct access

Guidelines: Nest when the child doesn't make sense without the parent Limit nesting to 2-3 levels (/a/1/b/2/c/3 is too deep) Provide top-level access if resources have global identity

Resource Modeling Example

Text

E-commerce API Resource Model:
 
/products                     # All products
/products/{id}                # Single product
/products/{id}/reviews        # Product's reviews
/products/{id}/variants       # Product variants (sizes, colors)
 
/categories                   # All categories
/categories/{id}              # Single category
/categories/{id}/products     # Products in category
 
/users                        # All users
/users/{id}                   # Single user
/users/{id}/addresses         # User's addresses
/users/{id}/payment-methods   # User's payment methods
 
/orders                       # All orders (admin access)
/orders/{id}                  # Single order
/orders/{id}/items            # Order line items
/orders/{id}/shipments        # Order shipments
 
/carts                        # Shopping carts
/carts/{id}/items             # Items in cart
 
# Action-oriented resources (when CRUD doesn't fit)
/checkout                     # Convert cart to order
/password-reset               # Password reset flow
/search                       # Cross-resource search

Naming Conventions

Consistent naming is critical for API usability. Developers should be able to guess endpoint names based on patterns they've observed. URL Path Conventions:

URL Naming Best Practices
Rule	Good	Avoid
Use nouns, not verbs	/users, /products	/getUsers, /createProduct
Use plural nouns for collections	/users/42	/user/42
Use lowercase	/user-profiles	/userProfiles, /User_Profiles
Use hyphens for multi-word	/user-profiles	/user_profiles, /userprofiles
No file extensions	/users/42	/users/42.json
No trailing slashes	/users/42	/users/42/

Query Parameter Conventions: Query parameters should follow consistent patterns:

Query Parameter Patterns

HTTP

# Filtering: field name as parameter
GET /products?category=electronics&min_price=100&max_price=500
 
# Sorting: explicit sort parameter with optional order
GET /products?sort=price&order=asc
GET /products?sort=-price  # Prefix with - for descending
 
# Pagination: consistent naming
GET /products?page=2&per_page=20
GET /products?limit=20&offset=40
GET /products?cursor=abc123
 
# Field selection: explicit fields parameter
GET /users/42?fields=id,name,email
 
# Expansion: include related resources
GET /orders/1001?expand=customer,items
 
# Search: use 'q' for search query
GET /products?q=wireless+headphones

JSON Field Naming: Choose and consistently apply a case convention:

Case	Example	Common In
camelCase	`firstName`, `createdAt`	JavaScript ecosystems
snake_case	`first_name`, `created_at`	Ruby, Python ecosystems
kebab-case	`first-name`	Rare in JSON; conflicts with math operators

Recommendation: Match your primary consumer language. If most clients are JavaScript apps, use camelCase. If Python, use snake_case. The key is consistency —never mix cases within an API.

Date and Time Formats

Always use ISO 8601 for dates and times: 2024-01-15T10:30:00Z . Include timezone (preferably UTC with 'Z' suffix). Never use locale-specific formats like 'MM/DD/YYYY'. This eliminates parsing ambiguity across clients.

Versioning Strategies

APIs evolve over time. New features are added, bugs are fixed, and occasionally breaking changes are necessary. Versioning provides a mechanism to manage this evolution without disrupting existing clients. Versioning Approaches:

API Versioning Strategies
Strategy	Example	Pros	Cons
URL Path	/api/v2/users	Explicit, easy to see, cacheable	URL pollution, hard for client library migration
Query Parameter	/api/users?version=2	Non-breaking URL, easy to default	Less visible, can be forgotten
Header	Api-Version: 2	Clean URLs, flexible negotiation	Hidden, harder to test/debug
Content Negotiation	Accept: application/vnd.api.v2+json	RESTful, precise format control	Complex, verbose

URL Path Versioning (Most Common):

URL Path Versioning

HTTP

# Version in URL path - most common approach
GET https://api.example.com/v1/users/42
GET https://api.example.com/v2/users/42
 
# V2 might have different response structure:
# v1: {"id": 42, "name": "Alice", "email": "alice@example.com"}
# v2: {"id": 42, "account": {"email": "alice@example.com"}, "profile": {"name": "Alice"}}

Header-Based Versioning (Stripe's Approach):

Header-Based Versioning

HTTP

# Request with version header
GET /v1/customers/cus_123 HTTP/1.1
Host: api.stripe.com
Stripe-Version: 2024-01-15
 
# Response adapts to requested version
# If version not specified, uses account's default version

Versioning Best Practices

•Start with v1: Always version from the beginning, even before breaking changes occur
•Increment rarely: Break only when absolutely necessary; additive changes don't need new versions
•Support multiple versions: Maintain old versions for a generous period (12-24 months)
•Communicate deprecation: Announce deprecation timeline well in advance
•Provide migration guides: Document exactly what changed and how to upgrade
•Use semantic versioning internally: Even if only major versions are public, track minor/patch internally

Evolutionary Design

Good API design minimizes breaking changes. Add new fields (don't remove old ones). Add new endpoints (don't change existing behavior). If a field meaning changes, create a new field with a new name. Well-designed APIs can evolve for years without version bumps.

Rate Limiting

Rate limiting protects APIs from abuse, ensures fair resource distribution, and maintains service quality. Every public API needs rate limiting. Common Rate Limiting Algorithms:

Rate Limiting Algorithms
Algorithm	How It Works	Characteristics
Fixed Window	Count requests per fixed time window (e.g., per minute)	Simple but burst at window edges
Sliding Window	Count requests in rolling time window	Smoother but more complex
Token Bucket	Tokens refill at constant rate; requests consume tokens	Allows controlled bursts
Leaky Bucket	Requests enter bucket, drain at fixed rate	Constant output rate, smooths traffic

Rate Limit Headers: Always communicate rate limit status to clients:

Rate Limit Headers

HTTP

# Successful response with rate limit info
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1705312860
 
# Rate limit exceeded
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312860
Retry-After: 45
Content-Type: application/json
 
{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded the rate limit of 100 requests per minute.",
  "retry_after": 45
}

Rate Limiting Strategies

•Per-user limits: Different limits for authenticated users vs. API keys vs. anonymous
•Per-endpoint limits: Expensive operations (search, reports) have lower limits than CRUD
•Burst allowance: Allow short bursts above sustained rate for legitimate use patterns
•Tiered limits: Premium tiers get higher limits (monetization strategy)
•Graceful degradation: Return cached/degraded responses before returning 429

Client-Side Best Practices

Good API clients respect rate limits gracefully: Check remaining quota before making requests, implement exponential backoff on 429 responses, spread requests over time instead of bursting, and cache responses to reduce unnecessary calls.

Security Best Practices

API security is paramount. A security breach can compromise user data, damage reputation, and violate regulations. Security must be designed in from the start, not bolted on later. Transport Security:

Transport Layer Security

•HTTPS Only: Never support plain HTTP. Redirect HTTP to HTTPS or reject outright.
•TLS 1.2+: Disable older TLS/SSL versions with known vulnerabilities.
•HSTS: Send Strict-Transport-Security header to prevent downgrade attacks.
•Certificate Pinning: For mobile apps, pin expected certificates to prevent MITM.

Authentication Security:

Authentication Best Practices
Practice	Implementation
Use tokens, not passwords	Issue JWTs or opaque tokens; never transmit passwords repeatedly
Short token expiry	Access tokens: 15 min to 1 hour; use refresh tokens for longer sessions
Secure token storage	Client-side: secure storage, not localStorage; Server-side: encrypted, not logs
Token revocation	Maintain revocation list or use short-lived tokens
Scope limitation	Tokens should have minimal necessary permissions

Input Validation and Injection Prevention:

Security Validation

Text

VALIDATION CHECKLIST:
 
✓ Validate all input on the server (never trust client validation)
✓ Validate data types, lengths, formats, and ranges
✓ Use parameterized queries for database access (prevent SQL injection)
✓ Escape output for context (HTML, JSON, etc.)
✓ Validate Content-Type matches actual body format
✓ Limit request body size (prevent DoS)
✓ Validate file uploads (type, size, and scan for malware)
 
NEVER:
✗ Interpolate user input into SQL queries
✗ Execute user-provided code (eval)
✗ Include user input in system commands
✗ Trust client-reported Content-Type without validation

Authorization and Access Control:

Authorization Principles

•Default deny: No access unless explicitly granted
•Check every request: Don't rely on hidden URLs; verify authorization on each endpoint
•Object-level authorization: Verify user can access the specific resource, not just the resource type
•Function-level authorization: Verify user can perform the specific action
•Avoid IDOR: Insecure Direct Object References allow guessing resource IDs; verify ownership

OWASP API Security Top 10

The OWASP API Security Top 10 lists common API vulnerabilities: Broken Object Level Authorization, Broken Authentication, Excessive Data Exposure, Lack of Resources & Rate Limiting, Broken Function Level Authorization, Mass Assignment, Security Misconfiguration, Injection, Improper Assets Management, and Insufficient Logging & Monitoring. Study and test for these.

Documentation

An API is only as good as its documentation. Developers evaluate APIs by their docs before writing any code. Poor documentation is a dealbreaker. Documentation Components:

Essential Documentation Elements

•Getting Started Guide: Quick path to first successful API call (5-10 minutes)
•Authentication Guide: How to obtain and use credentials, with code examples
•API Reference: Complete endpoint documentation with parameters, responses, errors
•Tutorials: Step-by-step guides for common use cases
•Code Examples: Samples in popular languages (JavaScript, Python, Ruby, cURL)
•Changelog: What changed in each version, migration guides for breaking changes
•Status Page: Real-time API health and incident history
•SDKs and Libraries: Official client libraries with documentation

API Reference Best Practices: Each endpoint should document:

Endpoint Documentation Template
Markdown
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
## Create Order
 
Creates a new order for the authenticated user.
 
### Endpoint
 
```
POST /api/v2/orders
```
 
### Authentication
 
Requires Bearer token with `orders:write` scope.
 
### Request Body
 
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| items | array | Yes | Array of order items |
| items[].product_id | string | Yes | Product identifier |
| items[].quantity | integer | Yes | Quantity (1-99) |
| shipping_address_id | string | Yes | Address for delivery |
| notes | string | No | Order notes (max 500 chars) |
 
### Response
 
**201 Created**
```json
{
  "id": "ord_abc123",
  "status": "pending",
  "items": [...],
  "total": 99.99,
  "created_at": "2024-01-15T10:30:00Z"
}
```
 
### Errors
 
| Status | Code | Description |
|--------|------|-------------|
| 400 | invalid_request | Malformed request body |
| 401 | unauthorized | Invalid or missing token |
| 422 | validation_error | Request failed validation |
| 422 | insufficient_stock | Product out of stock |

Interactive Documentation

Modern APIs provide interactive documentation (Swagger UI, Redocly, Postman) where developers can explore endpoints and make real API calls without leaving the docs. This 'try it now' capability dramatically improves developer experience and reduces time to first successful integration.

API Design

The Art and Science of API Design

RESTful Design Principles

Resource Modeling

Naming Conventions

Versioning Strategies

Rate Limiting

Security Best Practices

Authorization Principles

Documentation

There’s more to understand.

API Design

The Art and Science of API Design

RESTful Design Principles

Resource Modeling

Naming Conventions

Versioning Strategies

Rate Limiting

Security Best Practices

Authorization Principles

Documentation

There’s more to understand.