api-design-knowledge

name	api-design-knowledge
description	API Design knowledge base. Provides REST constraints, Richardson Maturity Model, HTTP semantics, content negotiation, and GraphQL/gRPC comparison for API audits and generation.

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

• 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)

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 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