API Design Knowledge

API Design Knowledge Base

Quick reference for API design patterns, REST best practices, and PHP implementation guidelines.

Core Principles

REST Constraints

Richardson Maturity Model

HTTP Methods Semantics

Status Code Guide

Content Negotiation

API Style Comparison

Quick Checklists

API Design Checklist

• Resources use nouns, not verbs (/orders not /getOrders)
• Consistent naming convention (kebab-case or camelCase)
• Proper HTTP methods for operations
• Meaningful status codes (not always 200)
• Pagination for list endpoints
• Filtering and sorting support
• Versioning strategy defined
• Error responses follow RFC 7807
• Rate limiting with proper headers
• CORS configured for browser clients

Security Checklist

• Authentication on all endpoints (except public)
• Authorization checks per resource
• Input validation at API boundary
• Rate limiting per client/IP
• HTTPS only (no HTTP)
• No sensitive data in URLs
• Proper CORS policy
• Security headers set

Detection Patterns

# REST endpoint definitions
Grep: "#\[Route|@Route|->get\(|->post\(|->put\(|->delete\(" --glob "**/*.php"
Glob: **/Controller/**/*.php
Glob: **/Action/**/*.php

# Status code usage
Grep: "->setStatusCode\(|Response\(.*[0-9]{3}|JsonResponse\(" --glob "**/*.php"

# Content negotiation
Grep: "Accept|Content-Type|application/json" --glob "**/*.php"

# API versioning
Grep: "/v[0-9]/|api-version|Accept.*vnd\." --glob "**/*.php"

# Error handling
Grep: "ProblemDetails|RFC7807|application/problem" --glob "**/*.php"
Grep: "JsonResponse.*4[0-9]{2}|JsonResponse.*5[0-9]{2}" --glob "**/*.php"

# Pagination
Grep: "page|per_page|limit|offset|cursor" --glob "**/Controller/**/*.php"

Advanced API Patterns

Cursor-Based Pagination (High-Load)

API Rate Limiting Algorithms

Rate Limit Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After (on 429).

gRPC for PHP

GraphQL N+1 Prevention

References

For detailed information, load these reference files:

• references/rest-patterns.md — Richardson Maturity details, HATEOAS, pagination, filtering, versioning strategies
• references/error-handling.md — RFC 7807 Problem Details, error response patterns, GraphQL errors, PHP implementation
• references/advanced-api.md — Cursor-based pagination, API rate limiting (token bucket, sliding window), gRPC PHP integration, GraphQL N+1 solutions

Converted and distributed by TomeVault — claim your Tome and manage your conversions.