Api Design Reviewer

API Design Reviewer

Comprehensive analysis and review of REST API designs against conventions, best practices, and industry standards. Helps engineering teams build consistent, maintainable, well-designed APIs through automated linting, breaking-change detection, and design scorecards.

Core Capabilities

• API linting & convention analysis — resource naming (kebab-case URLs, camelCase fields), HTTP method usage, URL structure, status-code compliance, error-format consistency, and documentation coverage.
• Breaking change detection — endpoint removal, response-shape changes, field removal/rename, type changes, new required fields, and status-code changes between two spec versions, with migration guides.
• API design scoring — weighted scorecard across Consistency (30%), Documentation (20%), Security (20%), Usability (15%), and Performance (15%), with letter grades A–F and recommendations.

When to Use

• Designing a new REST API or reviewing an API contract.
• Validating an OpenAPI/Swagger spec against REST conventions.
• Managing API versioning and detecting breaking changes between releases.
• Gating deployments on API design quality in CI.

Clarify First

Before producing the review, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• [ ] Which output — lint report, design scorecard, or breaking-change detection (selects api_linter.py, api_scorecard.py, or breaking_change_detector.py)
• [ ] Spec file(s) — the OpenAPI/Swagger JSON, or the two versions to diff (the input the tools parse)
• [ ] Quality bar / CI gate — minimum grade or fail-on-breaking (sets --min-grade / --exit-on-breaking and how strict the verdict is)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Tools

References

Load the reference that matches the task — keep this file lean and pull detail on demand:

• [references/rest-design-patterns.md](references/rest-design-patterns.md) — REST naming/method/URL principles, versioning strategies, pagination patterns, error formats and status codes, auth/RBAC patterns, rate limiting, HATEOAS, idempotency, backward-compatibility rules, OpenAPI validation, performance, and security best practices. Read when designing or reviewing endpoints.
• [references/tooling-ci-and-troubleshooting.md](references/tooling-ci-and-troubleshooting.md) — the three tools' features, CI/CD and pre-commit integration, best-practices and anti-pattern checklists, troubleshooting table, success criteria, and full CLI flag references. Read when wiring tools into pipelines or debugging.
• [references/rest_design_rules.md](references/rest_design_rules.md) — detailed REST design rules reference (resources vs actions, HTTP method semantics with worked examples). Read for an in-depth rules catalog.
• [references/api_antipatterns.md](references/api_antipatterns.md) — common API anti-patterns (verb-based URLs / RPC trap and more) with bad/good examples and recommended fixes. Read when auditing an existing API for design smells.

Scope & Limitations

This skill covers:

• Linting OpenAPI 3.x and Swagger 2.0 JSON specifications against REST conventions
• Detecting breaking, potentially-breaking, and non-breaking changes between two spec versions
• Scoring API design quality across consistency, documentation, security, usability, and performance
• Generating actionable migration guides when breaking changes are found

This skill does NOT cover:

• Runtime API testing, load testing, or contract testing (see api-test-suite-builder)
• GraphQL, gRPC, or WebSocket API design review
• Auto-generation of OpenAPI specs from code or server stubs
• Authentication flow implementation or OAuth server configuration (see senior-security in engineering/)

Integration Points

Common API Anti-Patterns and How to Avoid Them

Introduction

This document outlines common anti-patterns in REST API design that can lead to poor developer experience, maintenance nightmares, and scalability issues. Each anti-pattern is accompanied by examples and recommended solutions.

1. Verb-Based URLs (The RPC Trap)

Anti-Pattern

Using verbs in URLs instead of treating endpoints as resources.

❌ Bad Examples:
POST /api/getUsers
POST /api/createUser
GET  /api/deleteUser/123
POST /api/updateUserPassword
GET  /api/calculateOrderTotal/456

Why It's Bad

• Violates REST principles
• Makes the API feel like RPC instead of REST
• HTTP methods lose their semantic meaning
• Reduces cacheability
• Harder to understand resource relationships

Solution

✅ Good Examples:
GET    /api/users                    # Get users
POST   /api/users                    # Create user
DELETE /api/users/123               # Delete user
PATCH  /api/users/123/password      # Update password
GET    /api/orders/456/total        # Get order total

2. Inconsistent Naming Conventions

Anti-Pattern

Mixed naming conventions across the API.

❌ Bad Examples:
{
  "user_id": 123,           // snake_case
  "firstName": "John",      // camelCase
  "last-name": "Doe",       // kebab-case
  "EMAIL": "john@example.com", // UPPER_CASE
  "IsActive": true          // PascalCase
}

Why It's Bad

• Confuses developers
• Increases cognitive load
• Makes code generation difficult
• Reduces API adoption

Solution

✅ Choose one convention and stick to it (camelCase recommended):
{
  "userId": 123,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "isActive": true
}

3. Ignoring HTTP Status Codes

Anti-Pattern

Always returning HTTP 200 regardless of the actual result.

❌ Bad Example:
HTTP/1.1 200 OK
{
  "status": "error",
  "code": 404,
  "message": "User not found"
}

Why It's Bad

• Breaks HTTP semantics
• Prevents proper error handling by clients
• Breaks caching and proxies
• Makes monitoring and debugging harder

Solution

✅ Good Example:
HTTP/1.1 404 Not Found
{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "User with ID 123 not found",
    "requestId": "req-abc123"
  }
}

4. Overly Complex Nested Resources

Anti-Pattern

Creating deeply nested URL structures that are hard to navigate.

❌ Bad Example:
/companies/123/departments/456/teams/789/members/012/projects/345/tasks/678/comments/901

Why It's Bad

• URLs become unwieldy
• Creates tight coupling between resources
• Makes independent resource access difficult
• Complicates authorization logic

Solution

✅ Good Examples:
/tasks/678                    # Direct access to task
/tasks/678/comments          # Task comments
/users/012/tasks             # User's tasks
/projects/345?team=789       # Project filtering

5. Inconsistent Error Response Formats

Anti-Pattern

Different error response structures across endpoints.

❌ Bad Examples:
# Endpoint 1
{"error": "Invalid email"}

# Endpoint 2  
{"success": false, "msg": "User not found", "code": 404}

# Endpoint 3
{"errors": [{"field": "name", "message": "Required"}]}

Why It's Bad

• Makes error handling complex for clients
• Reduces code reusability
• Poor developer experience

Solution

✅ Standardized Error Format:
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email address is not valid"
      }
    ],
    "requestId": "req-123456",
    "timestamp": "2024-02-16T13:00:00Z"
  }
}

6. Missing or Poor Pagination

Anti-Pattern

Returning all results in a single response or inconsistent pagination.

❌ Bad Examples:
# No pagination (returns 10,000 records)
GET /api/users

# Inconsistent pagination parameters
GET /api/users?page=1&size=10
GET /api/orders?offset=0&limit=20
GET /api/products?start=0&count=50

Why It's Bad

• Can cause performance issues
• May overwhelm clients
• Inconsistent pagination parameters confuse developers
• No way to estimate total results

Solution

✅ Good Example:
GET /api/users?page=1&pageSize=10

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 150,
    "totalPages": 15,
    "hasNext": true,
    "hasPrev": false
  }
}

7. Exposing Internal Implementation Details

Anti-Pattern

URLs and field names that reflect database structure or internal architecture.

❌ Bad Examples:
/api/user_table/123
/api/db_orders
/api/legacy_customer_data
/api/temp_migration_users

Response fields:
{
  "user_id_pk": 123,
  "internal_ref_code": "usr_abc",
  "db_created_timestamp": 1645123456
}

Why It's Bad

• Couples API to internal implementation
• Makes refactoring difficult
• Exposes unnecessary technical details
• Reduces API longevity

Solution

✅ Good Examples:
/api/users/123
/api/orders
/api/customers

Response fields:
{
  "id": 123,
  "referenceCode": "usr_abc",
  "createdAt": "2024-02-16T13:00:00Z"
}

8. Overloading Single Endpoint

Anti-Pattern

Using one endpoint for multiple unrelated operations based on request parameters.

❌ Bad Example:
POST /api/user-actions
{
  "action": "create_user",
  "userData": {...}
}

POST /api/user-actions  
{
  "action": "delete_user",
  "userId": 123
}

POST /api/user-actions
{
  "action": "send_email",
  "userId": 123,
  "emailType": "welcome"
}

Why It's Bad

• Breaks REST principles
• Makes documentation complex
• Complicates client implementation
• Reduces discoverability

Solution

✅ Good Examples:
POST   /api/users              # Create user
DELETE /api/users/123         # Delete user  
POST   /api/users/123/emails   # Send email to user

9. Lack of Versioning Strategy

Anti-Pattern

Making breaking changes without version management.

❌ Bad Examples:
# Original API
{
  "name": "John Doe",
  "age": 30
}

# Later (breaking change with no versioning)
{
  "firstName": "John",
  "lastName": "Doe", 
  "birthDate": "1994-02-16"
}

Why It's Bad

• Breaks existing clients
• Forces all clients to update simultaneously
• No graceful migration path
• Reduces API stability

Solution

✅ Good Examples:
# Version 1
GET /api/v1/users/123
{
  "name": "John Doe",
  "age": 30
}

# Version 2 (with both versions supported)
GET /api/v2/users/123
{
  "firstName": "John",
  "lastName": "Doe",
  "birthDate": "1994-02-16",
  "age": 30  // Backwards compatibility
}

10. Poor Error Messages

Anti-Pattern

Vague, unhelpful, or technical error messages.

❌ Bad Examples:
{"error": "Something went wrong"}
{"error": "Invalid input"}
{"error": "SQL constraint violation: FK_user_profile_id"}
{"error": "NullPointerException at line 247"}

Why It's Bad

• Doesn't help developers fix issues
• Increases support burden
• Poor developer experience
• May expose sensitive information

Solution

✅ Good Examples:
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The email address is required and must be in a valid format",
    "details": [
      {
        "field": "email",
        "code": "REQUIRED",
        "message": "Email address is required"
      }
    ]
  }
}

11. Ignoring Content Negotiation

Anti-Pattern

Hard-coding response format without considering client preferences.

❌ Bad Example:
# Always returns JSON regardless of Accept header
GET /api/users/123
Accept: application/xml
# Returns JSON anyway

Why It's Bad

• Reduces API flexibility
• Ignores HTTP standards
• Makes integration harder for diverse clients

Solution

✅ Good Example:
GET /api/users/123
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0"?>
<user>
  <id>123</id>
  <name>John Doe</name>
</user>

12. Stateful API Design

Anti-Pattern

Maintaining session state on the server between requests.

❌ Bad Example:
# Step 1: Initialize session
POST /api/session/init

# Step 2: Set context (requires step 1)
POST /api/session/set-user/123

# Step 3: Get data (requires steps 1 & 2)
GET /api/session/user-data

Why It's Bad

• Breaks REST statelessness principle
• Reduces scalability
• Makes caching difficult
• Complicates error recovery

Solution

✅ Good Example:
# Self-contained requests
GET /api/users/123/data
Authorization: Bearer jwt-token-with-context

13. Inconsistent HTTP Method Usage

Anti-Pattern

Using HTTP methods inappropriately or inconsistently.

❌ Bad Examples:
GET  /api/users/123/delete    # DELETE operation with GET
POST /api/users/123/get       # GET operation with POST
PUT  /api/users               # Creating with PUT on collection
GET  /api/users/search        # Search with side effects

Why It's Bad

• Violates HTTP semantics
• Breaks caching and idempotency expectations
• Confuses developers and tools

Solution

✅ Good Examples:
DELETE /api/users/123         # Delete with DELETE
GET    /api/users/123         # Get with GET
POST   /api/users             # Create on collection
GET    /api/users?q=search    # Safe search with GET

14. Missing Rate Limiting Information

Anti-Pattern

Not providing rate limiting information to clients.

❌ Bad Example:
HTTP/1.1 429 Too Many Requests
{
  "error": "Rate limit exceeded"
}

Why It's Bad

• Clients don't know when to retry
• No information about current limits
• Difficult to implement proper backoff strategies

Solution

✅ Good Example:
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 3600

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "retryAfter": 3600
  }
}

15. Chatty API Design

Anti-Pattern

Requiring multiple API calls to accomplish common tasks.

❌ Bad Example:
# Get user profile requires 4 API calls
GET /api/users/123           # Basic info
GET /api/users/123/profile   # Profile details
GET /api/users/123/settings  # User settings
GET /api/users/123/stats     # User statistics

Why It's Bad

• Increases latency
• Creates network overhead
• Makes mobile apps inefficient
• Complicates client implementation

Solution

✅ Good Examples:
# Single call with expansion
GET /api/users/123?include=profile,settings,stats

# Or provide composite endpoints
GET /api/users/123/dashboard

# Or batch operations
POST /api/batch
{
  "requests": [
    {"method": "GET", "url": "/users/123"},
    {"method": "GET", "url": "/users/123/profile"}
  ]
}

16. No Input Validation

Anti-Pattern

Accepting and processing invalid input without proper validation.

❌ Bad Example:
POST /api/users
{
  "email": "not-an-email",
  "age": -5,
  "name": ""
}

# API processes this and fails later or stores invalid data

Why It's Bad

• Leads to data corruption
• Security vulnerabilities
• Difficult to debug issues
• Poor user experience

Solution

✅ Good Example:
POST /api/users
{
  "email": "not-an-email",
  "age": -5,
  "name": ""
}

HTTP/1.1 400 Bad Request
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid data",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email must be a valid email address"
      },
      {
        "field": "age",
        "code": "INVALID_RANGE",
        "message": "Age must be between 0 and 150"
      },
      {
        "field": "name",
        "code": "REQUIRED",
        "message": "Name is required and cannot be empty"
      }
    ]
  }
}

17. Synchronous Long-Running Operations

Anti-Pattern

Blocking the client with long-running operations in synchronous endpoints.

❌ Bad Example:
POST /api/reports/generate
# Client waits 30 seconds for response

Why It's Bad

• Poor user experience
• Timeouts and connection issues
• Resource waste on client and server
• Doesn't scale well

Solution

✅ Good Example:
# Async pattern
POST /api/reports
HTTP/1.1 202 Accepted
Location: /api/reports/job-123
{
  "jobId": "job-123",
  "status": "processing",
  "estimatedCompletion": "2024-02-16T13:05:00Z"
}

# Check status
GET /api/reports/job-123
{
  "jobId": "job-123",
  "status": "completed",
  "result": "/api/reports/download/report-456"
}

Prevention Strategies

1. API Design Reviews

• Implement mandatory design reviews
• Use checklists based on these anti-patterns
• Include multiple stakeholders

2. API Style Guides

• Create and enforce API style guides
• Use linting tools for consistency
• Regular training for development teams

3. Automated Testing

• Test for common anti-patterns
• Include contract testing
• Monitor API usage patterns

4. Documentation Standards

• Require comprehensive API documentation
• Include examples and error scenarios
• Keep documentation up-to-date

5. Client Feedback

• Regularly collect feedback from API consumers
• Monitor API usage analytics
• Conduct developer experience surveys

Conclusion

Avoiding these anti-patterns requires:

• Understanding REST principles
• Consistent design standards
• Regular review and refactoring
• Focus on developer experience
• Proper tooling and automation

Remember: A well-designed API is an asset that grows in value over time, while a poorly designed API becomes a liability that hampers development and adoption.

REST API Design Rules Reference

Core Principles

1. Resources, Not Actions

REST APIs should focus on resources (nouns) rather than actions (verbs). The HTTP methods provide the actions.

✅ Good:
GET    /users           # Get all users
GET    /users/123       # Get user 123
POST   /users           # Create new user
PUT    /users/123       # Update user 123
DELETE /users/123       # Delete user 123

❌ Bad:
POST   /getUsers
POST   /createUser
POST   /updateUser/123
POST   /deleteUser/123

2. Hierarchical Resource Structure

Use hierarchical URLs to represent resource relationships:

/users/123/orders/456/items/789

But avoid excessive nesting (max 3-4 levels):

❌ Too deep: /companies/123/departments/456/teams/789/members/012/tasks/345
✅ Better:   /tasks/345?member=012&team=789

Resource Naming Conventions

URLs Should Use Kebab-Case

✅ Good:
/user-profiles
/order-items
/shipping-addresses

❌ Bad:
/userProfiles
/user_profiles
/orderItems

Collections vs Individual Resources

Collection:   /users
Individual:   /users/123
Sub-resource: /users/123/orders

Pluralization Rules

• Use plural nouns for collections: /users, /orders
• Use singular nouns for single resources: /user-profile, /current-session
• Be consistent throughout your API

HTTP Methods Usage

GET - Safe and Idempotent

• Purpose: Retrieve data
• Safe: No side effects
• Idempotent: Multiple calls return same result
• Request Body: Should not have one
• Cacheable: Yes

GET /users/123
GET /users?status=active&limit=10

POST - Not Idempotent

• Purpose: Create resources, non-idempotent operations
• Safe: No
• Idempotent: No
• Request Body: Usually required
• Cacheable: Generally no

POST /users              # Create new user
POST /users/123/activate # Activate user (action)

PUT - Idempotent

• Purpose: Create or completely replace a resource
• Safe: No
• Idempotent: Yes
• Request Body: Required (complete resource)
• Cacheable: No

PUT /users/123  # Replace entire user resource

PATCH - Partial Update

• Purpose: Partially update a resource
• Safe: No
• Idempotent: Not necessarily
• Request Body: Required (partial resource)
• Cacheable: No

PATCH /users/123  # Update only specified fields

DELETE - Idempotent

• Purpose: Remove a resource
• Safe: No
• Idempotent: Yes (same result if called multiple times)
• Request Body: Usually not needed
• Cacheable: No

DELETE /users/123

Status Codes

Success Codes (2xx)

• 200 OK: Standard success response
• 201 Created: Resource created successfully (POST)
• 202 Accepted: Request accepted for processing (async)
• 204 No Content: Success with no response body (DELETE, PUT)

Redirection Codes (3xx)

• 301 Moved Permanently: Resource permanently moved
• 302 Found: Temporary redirect
• 304 Not Modified: Use cached version

Client Error Codes (4xx)

• 400 Bad Request: Invalid request syntax or data
• 401 Unauthorized: Authentication required
• 403 Forbidden: Access denied (user authenticated but not authorized)
• 404 Not Found: Resource not found
• 405 Method Not Allowed: HTTP method not supported
• 409 Conflict: Resource conflict (duplicates, version mismatch)
• 422 Unprocessable Entity: Valid syntax but semantic errors
• 429 Too Many Requests: Rate limit exceeded

Server Error Codes (5xx)

• 500 Internal Server Error: Unexpected server error
• 502 Bad Gateway: Invalid response from upstream server
• 503 Service Unavailable: Server temporarily unavailable
• 504 Gateway Timeout: Upstream server timeout

URL Design Patterns

Query Parameters for Filtering

GET /users?status=active
GET /users?role=admin&department=engineering
GET /orders?created_after=2024-01-01&status=pending

Pagination Parameters

# Offset-based
GET /users?offset=20&limit=10

# Cursor-based
GET /users?cursor=eyJpZCI6MTIzfQ&limit=10

# Page-based
GET /users?page=3&page_size=10

Sorting Parameters

GET /users?sort=created_at          # Ascending
GET /users?sort=-created_at         # Descending (prefix with -)
GET /users?sort=last_name,first_name # Multiple fields

Field Selection

GET /users?fields=id,name,email
GET /users/123?include=orders,profile
GET /users/123?exclude=internal_notes

Search Parameters

GET /users?q=john
GET /products?search=laptop&category=electronics

Response Format Standards

Consistent Response Structure

{
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com"
  },
  "meta": {
    "timestamp": "2024-02-16T13:00:00Z",
    "version": "1.0"
  }
}

Collection Responses

{
  "data": [
    {"id": 1, "name": "Item 1"},
    {"id": 2, "name": "Item 2"}
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "pageSize": 10,
    "totalPages": 15,
    "hasNext": true,
    "hasPrev": false
  },
  "meta": {
    "timestamp": "2024-02-16T13:00:00Z"
  }
}

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email address is not valid"
      }
    ],
    "requestId": "req-123456",
    "timestamp": "2024-02-16T13:00:00Z"
  }
}

Field Naming Conventions

Use camelCase for JSON Fields

✅ Good:
{
  "firstName": "John",
  "lastName": "Doe",
  "createdAt": "2024-02-16T13:00:00Z",
  "isActive": true
}

❌ Bad:
{
  "first_name": "John",
  "LastName": "Doe",
  "created-at": "2024-02-16T13:00:00Z"
}

Boolean Fields

Use positive, clear names with "is", "has", "can", or "should" prefixes:

✅ Good:
{
  "isActive": true,
  "hasPermission": false,
  "canEdit": true,
  "shouldNotify": false
}

❌ Bad:
{
  "active": true,
  "disabled": false,  // Double negative
  "permission": false // Unclear meaning
}

Date/Time Fields

• Use ISO 8601 format: 2024-02-16T13:00:00Z
• Include timezone information
• Use consistent field naming:

{
  "createdAt": "2024-02-16T13:00:00Z",
  "updatedAt": "2024-02-16T13:30:00Z",
  "deletedAt": null,
  "publishedAt": "2024-02-16T14:00:00Z"
}

Content Negotiation

Accept Headers

Accept: application/json
Accept: application/xml
Accept: application/json; version=1

Content-Type Headers

Content-Type: application/json
Content-Type: application/json; charset=utf-8
Content-Type: multipart/form-data

Versioning via Headers

Accept: application/vnd.myapi.v1+json
API-Version: 1.0

Caching Guidelines

Cache-Control Headers

Cache-Control: public, max-age=3600        # Cache for 1 hour
Cache-Control: private, max-age=0          # Don't cache
Cache-Control: no-cache, must-revalidate   # Always validate

ETags for Conditional Requests

HTTP/1.1 200 OK
ETag: "123456789"
Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT

# Client subsequent request:
If-None-Match: "123456789"
If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT

Security Headers

Authentication

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Authorization: Basic dXNlcjpwYXNzd29yZA==
Authorization: Api-Key abc123def456

CORS Headers

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization

Rate Limiting

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-RateLimit-Window: 3600

Rate Limit Exceeded Response

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "details": {
      "limit": 1000,
      "window": "1 hour",
      "retryAfter": 3600
    }
  }
}

Hypermedia (HATEOAS)

Links in Responses

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": {
      "href": "/users/123"
    },
    "orders": {
      "href": "/users/123/orders"
    },
    "edit": {
      "href": "/users/123",
      "method": "PUT"
    },
    "delete": {
      "href": "/users/123",
      "method": "DELETE"
    }
  }
}

Link Relations

• self: Link to the resource itself
• edit: Link to edit the resource
• delete: Link to delete the resource
• related: Link to related resources
• next/prev: Pagination links

Common Anti-Patterns to Avoid

1. Verbs in URLs

❌ Bad: /api/getUser/123
✅ Good: GET /api/users/123

2. Inconsistent Naming

❌ Bad: /user-profiles and /userAddresses
✅ Good: /user-profiles and /user-addresses

3. Deep Nesting

❌ Bad: /companies/123/departments/456/teams/789/members/012
✅ Good: /team-members/012?team=789

4. Ignoring HTTP Status Codes

❌ Bad: Always return 200 with error info in body
✅ Good: Use appropriate status codes (404, 400, 500, etc.)

5. Exposing Internal Structure

❌ Bad: /api/database_table_users
✅ Good: /api/users

6. No Versioning Strategy

❌ Bad: Breaking changes without version management
✅ Good: /api/v1/users or Accept: application/vnd.api+json;version=1

7. Inconsistent Error Responses

❌ Bad: Different error formats for different endpoints
✅ Good: Standardized error response structure

Best Practices Summary

1. Use nouns for resources, not verbs 2. Leverage HTTP methods correctly 3. Maintain consistent naming conventions 4. Implement proper error handling 5. Use appropriate HTTP status codes 6. Design for cacheability 7. Implement security from the start 8. Plan for versioning 9. Provide comprehensive documentation 10. Follow HATEOAS principles when applicable

Further Reading

• RFC 7231 - HTTP/1.1 Semantics and Content
• RFC 6570 - URI Template
• OpenAPI Specification
• REST API Design Best Practices
• HTTP Status Code Definitions

REST API Design Patterns

Read this when reviewing or designing endpoints — naming, versioning, pagination, error formats, auth, rate limiting, HATEOAS, idempotency, backward compatibility, OpenAPI validation, performance, and security.

REST Design Principles

Resource Naming Conventions

✅ Good Examples:
- /api/v1/users
- /api/v1/user-profiles
- /api/v1/orders/123/line-items

❌ Bad Examples:
- /api/v1/getUsers
- /api/v1/user_profiles
- /api/v1/orders/123/lineItems

HTTP Method Usage

• GET: Retrieve resources (safe, idempotent)
• POST: Create new resources (not idempotent)
• PUT: Replace entire resources (idempotent)
• PATCH: Partial resource updates (not necessarily idempotent)
• DELETE: Remove resources (idempotent)

URL Structure Best Practices

Collection Resources: /api/v1/users
Individual Resources: /api/v1/users/123
Nested Resources: /api/v1/users/123/orders
Actions: /api/v1/users/123/activate (POST)
Filtering: /api/v1/users?status=active&role=admin

Versioning Strategies

1. URL Versioning (Recommended)

/api/v1/users
/api/v2/users

Pros: Clear, explicit, easy to route Cons: URL proliferation, caching complexity

2. Header Versioning

GET /api/users
Accept: application/vnd.api+json;version=1

Pros: Clean URLs, content negotiation Cons: Less visible, harder to test manually

3. Media Type Versioning

GET /api/users
Accept: application/vnd.myapi.v1+json

Pros: RESTful, supports multiple representations Cons: Complex, harder to implement

4. Query Parameter Versioning

/api/users?version=1

Pros: Simple to implement Cons: Not RESTful, can be ignored

Pagination Patterns

Offset-Based Pagination

{
  "data": [...],
  "pagination": {
    "offset": 20,
    "limit": 10,
    "total": 150,
    "hasMore": true
  }
}

Cursor-Based Pagination

{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTIzfQ==",
    "hasMore": true
  }
}

Page-Based Pagination

{
  "data": [...],
  "pagination": {
    "page": 3,
    "pageSize": 10,
    "totalPages": 15,
    "totalItems": 150
  }
}

Error Response Formats

Standard Error Structure

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email address is not valid"
      }
    ],
    "requestId": "req-123456",
    "timestamp": "2024-02-16T13:00:00Z"
  }
}

HTTP Status Code Usage

• 400 Bad Request: Invalid request syntax or parameters
• 401 Unauthorized: Authentication required
• 403 Forbidden: Access denied (authenticated but not authorized)
• 404 Not Found: Resource not found
• 409 Conflict: Resource conflict (duplicate, version mismatch)
• 422 Unprocessable Entity: Valid syntax but semantic errors
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Unexpected server error

Authentication and Authorization Patterns

Bearer Token Authentication

Authorization: Bearer <token>

API Key Authentication

X-API-Key: <api-key>
Authorization: Api-Key <api-key>

OAuth 2.0 Flow

Authorization: Bearer <oauth-access-token>

Role-Based Access Control (RBAC)

{
  "user": {
    "id": "123",
    "roles": ["admin", "editor"],
    "permissions": ["read:users", "write:orders"]
  }
}

Rate Limiting Implementation

Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Response on Limit Exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "retryAfter": 3600
  }
}

HATEOAS (Hypermedia as the Engine of Application State)

Example Implementation

{
  "id": "123",
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": { "href": "/api/v1/users/123" },
    "orders": { "href": "/api/v1/users/123/orders" },
    "profile": { "href": "/api/v1/users/123/profile" },
    "deactivate": { 
      "href": "/api/v1/users/123/deactivate",
      "method": "POST"
    }
  }
}

Idempotency

Idempotent Methods

• GET: Always safe and idempotent
• PUT: Should be idempotent (replace entire resource)
• DELETE: Should be idempotent (same result)
• PATCH: May or may not be idempotent

Idempotency Keys

POST /api/v1/payments
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

Backward Compatibility Guidelines

Safe Changes (Non-Breaking)

• Adding optional fields to requests
• Adding fields to responses
• Adding new endpoints
• Making required fields optional
• Adding new enum values (with graceful handling)

Breaking Changes (Require Version Bump)

• Removing fields from responses
• Making optional fields required
• Changing field types
• Removing endpoints
• Changing URL structures
• Modifying error response formats

OpenAPI/Swagger Validation

Required Components

• API Information: Title, description, version
• Server Information: Base URLs and descriptions
• Path Definitions: All endpoints with methods
• Parameter Definitions: Query, path, header parameters
• Request/Response Schemas: Complete data models
• Security Definitions: Authentication schemes
• Error Responses: Standard error formats

Best Practices

• Use consistent naming conventions
• Provide detailed descriptions for all components
• Include examples for complex objects
• Define reusable components and schemas
• Validate against OpenAPI specification

Performance Considerations

Caching Strategies

Cache-Control: public, max-age=3600
ETag: "123456789"
Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT

Efficient Data Transfer

• Use appropriate HTTP methods
• Implement field selection (?fields=id,name,email)
• Support compression (gzip)
• Implement efficient pagination
• Use ETags for conditional requests

Resource Optimization

• Avoid N+1 queries
• Implement batch operations
• Use async processing for heavy operations
• Support partial updates (PATCH)

Security Best Practices

Input Validation

• Validate all input parameters
• Sanitize user data
• Use parameterized queries
• Implement request size limits

Authentication Security

• Use HTTPS everywhere
• Implement secure token storage
• Support token expiration and refresh
• Use strong authentication mechanisms

Authorization Controls

• Implement principle of least privilege
• Use resource-based permissions
• Support fine-grained access control
• Audit access patterns

Tooling, CI Integration, Best Practices, Troubleshooting & Tool Reference

Read this when wiring the tools into CI/pre-commit, applying the best-practice/anti-pattern checklists, troubleshooting, or needing full CLI flag references.

Tools and Scripts

api_linter.py

Analyzes API specifications for compliance with REST conventions and best practices.

Features:

• OpenAPI/Swagger spec validation
• Naming convention checks
• HTTP method usage validation
• Error format consistency
• Documentation completeness analysis

breaking_change_detector.py

Compares API specification versions to identify breaking changes.

Features:

• Endpoint comparison
• Schema change detection
• Field removal/modification tracking
• Migration guide generation
• Impact severity assessment

api_scorecard.py

Provides comprehensive scoring of API design quality.

Features:

• Multi-dimensional scoring
• Detailed improvement recommendations
• Letter grade assessment (A-F)
• Benchmark comparisons
• Progress tracking

Integration Examples

CI/CD Integration

- name: API Linting
  run: python scripts/api_linter.py openapi.json

- name: Breaking Change Detection
  run: python scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json

- name: API Scorecard
  run: python scripts/api_scorecard.py openapi.json

Pre-commit Hooks

#!/bin/bash
python engineering/api-design-reviewer/scripts/api_linter.py api/openapi.json
if [ $? -ne 0 ]; then
  echo "API linting failed. Please fix the issues before committing."
  exit 1
fi

Best Practices Summary

1. Consistency First: Maintain consistent naming, response formats, and patterns 2. Documentation: Provide comprehensive, up-to-date API documentation 3. Versioning: Plan for evolution with clear versioning strategies 4. Error Handling: Implement consistent, informative error responses 5. Security: Build security into every layer of the API 6. Performance: Design for scale and efficiency from the start 7. Backward Compatibility: Minimize breaking changes and provide migration paths 8. Testing: Implement comprehensive testing including contract testing 9. Monitoring: Add observability for API usage and performance 10. Developer Experience: Prioritize ease of use and clear documentation

Common Anti-Patterns to Avoid

1. Verb-based URLs: Use nouns for resources, not actions 2. Inconsistent Response Formats: Maintain standard response structures 3. Over-nesting: Avoid deeply nested resource hierarchies 4. Ignoring HTTP Status Codes: Use appropriate status codes for different scenarios 5. Poor Error Messages: Provide actionable, specific error information 6. Missing Pagination: Always paginate list endpoints 7. No Versioning Strategy: Plan for API evolution from day one 8. Exposing Internal Structure: Design APIs for external consumption, not internal convenience 9. Missing Rate Limiting: Protect your API from abuse and overload 10. Inadequate Testing: Test all aspects including error cases and edge conditions

Troubleshooting

Success Criteria

• Zero breaking changes detected between consecutive minor or patch releases (semver compliance)
• API consistency score (from api_scorecard.py) above 90 across all reviewed specifications
• Overall scorecard grade of B or higher (80+) before any API ships to production
• 100% of endpoints include at least one success response and one error response definition
• All path segments follow kebab-case naming and all schema properties follow camelCase naming with zero linter errors
• Breaking change reports generated and reviewed for every PR that modifies an OpenAPI spec
• Documentation coverage score above 85%, meaning every operation has a summary and every schema has a description

Tool Reference

api_linter.py

Purpose: Analyzes OpenAPI/Swagger JSON specifications for compliance with REST conventions and best practices. Checks naming conventions, HTTP method usage, URL structure, status codes, error formats, documentation completeness, and security configuration.

Usage:

python api_linter.py [OPTIONS] INPUT_FILE

Parameters:

Example:

python api_linter.py openapi.json
python api_linter.py --format json openapi.json > report.json
python api_linter.py --raw-endpoints endpoints.json
python api_linter.py --output lint-report.txt openapi.json

Output Formats:

• text -- Human-readable report with issue breakdown by category, severity icons, suggestions, and a scoring summary. Exits with code 1 if any errors are found, 0 otherwise.
• json -- Machine-readable JSON object with summary (total_endpoints, endpoints_with_issues, total_issues, errors, warnings, info, score) and issues array (severity, category, message, path, suggestion).

---

breaking_change_detector.py

Purpose: Compares two versions of an OpenAPI JSON specification and detects breaking changes including removed endpoints, modified response structures, removed fields, type changes, new required fields, parameter changes, and status code changes. Generates migration guides for each breaking change.

Usage:

python breaking_change_detector.py [OPTIONS] OLD_SPEC NEW_SPEC

Parameters:

Example:

python breaking_change_detector.py v1.json v2.json
python breaking_change_detector.py --format json v1.json v2.json > changes.json
python breaking_change_detector.py --exit-on-breaking --output report.txt v1.json v2.json

Output Formats:

• text -- Human-readable report listing each change with its type (breaking, potentially_breaking, non_breaking, enhancement), severity (critical, high, medium, low, info), category, path, message, impact description, and migration guide.
• json -- Machine-readable JSON object with summary (total_changes, breaking_changes, potentially_breaking_changes, non_breaking_changes, enhancements, and per-severity counts) and changes array (changeType, severity, category, path, message, oldValue, newValue, migrationGuide, impactDescription).

---

api_scorecard.py

Purpose: Generates a comprehensive API design quality scorecard by evaluating an OpenAPI JSON specification across five weighted dimensions: Consistency (30%), Documentation (20%), Security (20%), Usability (15%), and Performance (15%). Produces letter grades (A-F) per category and overall, with actionable improvement recommendations.

Usage:

python api_scorecard.py [OPTIONS] SPEC_FILE

Parameters:

Example:

python api_scorecard.py openapi.json
python api_scorecard.py --format json openapi.json > scorecard.json
python api_scorecard.py --min-grade B --output scorecard.txt openapi.json

Output Formats:

• text -- Human-readable scorecard showing API info, per-category scores with letter grades, issue counts, recommendations, and an overall weighted score with grade.
• json -- Machine-readable JSON object with apiInfo, categoryScores (per category: score, maxScore, weight, letterGrade, weightedScore, issues, recommendations), overallScore, overallGrade, totalEndpoints, and topRecommendations.