API Design Knowledge Base
Quick reference for API design patterns, REST best practices, and PHP implementation guidelines.
Core Principles
REST Constraints
| Constraint | Description | Implication |
|---|
| Client-Server | Separation of concerns | Independent evolution |
| Stateless | No server-side session state | Each request contains all info |
| Cacheable | Responses declare cacheability | Reduces server load |
| Uniform Interface | Standard resource operations | Predictable API surface |
| Layered System | Client can't tell if connected directly | Proxy, gateway, CDN support |
| Code on Demand (optional) | Server can send executable code | Rarely used in APIs |
Richardson Maturity Model
| Level | Name | Description | Example |
|---|
| 0 | Swamp of POX | Single endpoint, RPC-style | POST /api with action in body |
| 1 | Resources | Multiple endpoints per resource | GET /orders/123 |
| 2 | HTTP Verbs | Proper use of HTTP methods + status codes | DELETE /orders/123 → 204 |
| 3 | HATEOAS | Hypermedia controls in responses | Links to related actions |
HTTP Methods Semantics
| Method | Safe | Idempotent | Request Body | Typical Use |
|---|
| GET | Yes | Yes | No | Retrieve resource |
| HEAD | Yes | Yes | No | Check resource existence |
| POST | No | No | Yes | Create resource, trigger action |
| PUT | No | Yes | Yes | Replace resource entirely |
| PATCH | No | No | Yes | Partial update |
| DELETE | No | Yes | No | Remove resource |
| OPTIONS | Yes | Yes | No | CORS preflight, capabilities |
Status Code Guide
| Range | Category | Common Codes |
|---|
| 2xx | Success | 200 OK, 201 Created, 202 Accepted, 204 No Content |
| 3xx | Redirection | 301 Moved Permanently, 304 Not Modified |
| 4xx | Client Error | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests |
| 5xx | Server Error | 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout |
Content Negotiation
| Header | Purpose | Example |
|---|
| Accept | Client requests format | Accept: application/json |
| Content-Type | Body format declaration | Content-Type: application/json |
| Accept-Language | Localization | Accept-Language: en-US |
| Accept-Encoding | Compression | Accept-Encoding: gzip, br |
API Style Comparison
| Aspect | REST | GraphQL | gRPC |
|---|
| Protocol | HTTP/1.1+ | HTTP/1.1+ | HTTP/2 |
| Data format | JSON | JSON | Protobuf |
| Schema | OpenAPI (optional) | SDL (required) | .proto (required) |
| Caching | HTTP caching native | Complex (POST only) | Manual |
| Over-fetching | Common | Solved (client picks fields) | Solved (defined messages) |
| Under-fetching | Common (multiple calls) | Solved (nested queries) | Separate RPCs |
| Learning curve | Low | Medium | High |
| Best for | Public APIs, CRUD | Client-driven UIs, BFF | Internal services, streaming |
Quick Checklists
API Design Checklist
Security Checklist
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)
| Aspect | Offset-Based | Cursor-Based |
|---|
| URL | ?page=5&per_page=20 | ?cursor=abc123&limit=20 |
| Performance at scale | Degrades (OFFSET N) | Constant (WHERE id > X) |
| Consistency | Misses/duplicates on insert | Stable, no gaps |
| Random page access | Yes | No (sequential only) |
| Use case | Admin panels | Feeds, large datasets |
API Rate Limiting Algorithms
| Algorithm | Precision | Burst | PHP Implementation |
|---|
| Token Bucket | Medium | Allows burst | Redis Lua script |
| Sliding Window | High | Smooth | Redis sorted set |
| Fixed Window | Low | Edge burst | Redis INCR + EXPIRE |
| Leaky Bucket | High | No burst | Redis list |
Rate Limit Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After (on 429).
gRPC for PHP
| Factor | Choose REST | Choose gRPC |
|---|
| Client type | Browser, third-party | Internal services |
| Payload | Small-medium JSON | Large binary data |
| Streaming | Not needed | Real-time updates |
| PHP ecosystem | Mature | Limited (ext-grpc) |
GraphQL N+1 Prevention
| Technique | How | Complexity |
|---|
| DataLoader | Batch + cache per request | Medium |
| Query depth limit | Max 5-7 nesting levels | Low |
| Complexity scoring | Cost per field, reject expensive | Medium |
| Persisted queries | Whitelist allowed queries | Low |
References
For detailed information, load these reference files:
references/rest-patterns.md — Richardson Maturity details, HATEOAS, pagination, filtering, versioning strategiesreferences/error-handling.md — RFC 7807 Problem Details, error response patterns, GraphQL errors, PHP implementationreferences/advanced-api.md — Cursor-based pagination, API rate limiting (token bucket, sliding window), gRPC PHP integration, GraphQL N+1 solutions
