Awesome-claude-code api-design-knowledge

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

install

source · Clone the upstream repo

git clone https://github.com/dykyi-roman/awesome-claude-code

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/dykyi-roman/awesome-claude-code "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/api-design-knowledge" ~/.claude/skills/dykyi-roman-awesome-claude-code-api-design-knowledge && rm -rf "$T"

manifest: skills/api-design-knowledge/SKILL.md

source content

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

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