Stats
Actions
Tags
From acc
Provides REST constraints, Richardson Maturity Model, HTTP semantics, status codes, content negotiation, and GraphQL/gRPC comparisons for API audits and design.
How this skill is triggered — by the user, by Claude, or both
Slash command
/acc:api-design-knowledgeThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Quick reference for API design patterns, REST best practices, and PHP implementation guidelines.
Quick reference for API design patterns, REST best practices, and PHP implementation guidelines.
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
/orders not /getOrders)# 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"
| 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 |
| 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).
| 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) |
| 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 |
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 solutionsnpx claudepluginhub dykyi-roman/awesome-claude-code --plugin accProvides decision trees, patterns, and guidance for REST, gRPC, GraphQL API design including resource naming, schema, versioning, pagination, rate limiting, auth, and OpenAPI.
Guides API design decisions including REST vs GraphQL, resource modeling, versioning, error contracts, pagination, and authentication patterns.
Provides API design principles, comparisons, and best practices for REST, GraphQL, gRPC including resource naming, schema design, documentation with OpenAPI, versioning, and error handling.