Menu
API design principles for REST, GraphQL, and gRPC
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Web accessibility guidelines and implementation
Software architecture patterns, principles, and best practices
Code quality practices, linting, and refactoring
F5 Framework workflow commands for AI-assisted development
F5 Framework core workflow, quality gates, and behavioral modes
Database design, SQL, NoSQL, and data management
| name | api-design |
| description | API design principles for REST, GraphQL, and gRPC |
| category | skill |
| allowed-tools | Read, Write, Glob, Grep, Bash |
| user-invocable | true |
| context | inject |
API design knowledge for building clean, consistent, and developer-friendly APIs. This domain covers REST, GraphQL, gRPC, documentation standards, and best practices.
┌─────────────────────────────────────────────────────────────────────────────┐
│ API Types Comparison │
├──────────────┬──────────────┬──────────────┬──────────────┬─────────────────┤
│ Aspect │ REST │ GraphQL │ gRPC │ Best For │
├──────────────┼──────────────┼──────────────┼──────────────┼─────────────────┤
│ Protocol │ HTTP/1.1 │ HTTP/1.1 │ HTTP/2 │ │
│ Format │ JSON/XML │ JSON │ Protobuf │ │
│ Schema │ Optional │ Required │ Required │ │
│ │ (OpenAPI) │ (SDL) │ (.proto) │ │
│ Caching │ HTTP native │ Complex │ Manual │ │
│ Real-time │ Polling/SSE │ Subscriptions│ Streaming │ │
│ Learning │ Easy │ Medium │ Hard │ │
├──────────────┼──────────────┼──────────────┼──────────────┼─────────────────┤
│ Use Cases │ Public APIs │ Flexible │ Microservices│ │
│ │ CRUD apps │ Mobile apps │ Low latency │ │
│ │ Web services │ Aggregation │ High perf │ │
└──────────────┴──────────────┴──────────────┴──────────────┴─────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ REST Maturity Model │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Level 3: Hypermedia Controls (HATEOAS) │
│ ├── Self-documenting APIs │
│ ├── Discoverability via links │
│ └── Decoupled client-server evolution │
│ ↑ │
│ Level 2: HTTP Verbs + Status Codes │
│ ├── GET, POST, PUT, PATCH, DELETE │
│ ├── Proper status codes (200, 201, 404, etc.) │
│ └── Safe and idempotent methods │
│ ↑ │
│ Level 1: Resources │
│ ├── Multiple URIs for different resources │
│ ├── /users, /orders, /products │
│ └── Still using single HTTP verb │
│ ↑ │
│ Level 0: The Swamp of POX │
│ ├── Single URI for all operations │
│ ├── POST /api with action in body │
│ └── RPC-style over HTTP │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ Which API Style to Choose? │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Start Here │
│ │ │
│ ▼ │
│ Public API for third parties? │
│ │ │
│ ├── Yes → REST (with OpenAPI) │
│ │ • Easy to understand │
│ │ • Good tooling │
│ │ • HTTP caching │
│ │ │
│ └── No → Internal/Microservices? │
│ │ │
│ ├── Yes → Need real-time? │
│ │ │ │
│ │ ├── Yes → gRPC streaming │
│ │ │ │
│ │ └── No → High performance? │
│ │ │ │
│ │ ├── Yes → gRPC │
│ │ └── No → REST │
│ │ │
│ └── No → Mobile/Web frontend? │
│ │ │
│ ├── Multiple clients? → GraphQL │
│ ├── Complex queries? → GraphQL │
│ └── Simple CRUD? → REST │
│ │
└─────────────────────────────────────────────────────────────────┘
| Method | Idempotent | Safe | Cacheable | Request Body |
|---|---|---|---|---|
| GET | Yes | Yes | Yes | No |
| POST | No | No | No | Yes |
| PUT | Yes | No | No | Yes |
| PATCH | No* | No | No | Yes |
| DELETE | Yes | No | No | Optional |
| Code | Name | Usage |
|---|---|---|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST (resource created) |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Invalid syntax, validation error |
| 401 | Unauthorized | Missing/invalid authentication |
| 403 | Forbidden | Valid auth, no permission |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Resource conflict |
| 422 | Unprocessable | Semantic errors |
| 429 | Too Many Requests | Rate limited |
| 500 | Internal Error | Server error |
| Skill | Description |
|---|---|
| rest-principles | Core REST constraints and design |
| resource-naming | URI design and resource naming |
| http-methods | HTTP verb semantics |
| status-codes | HTTP status code usage |
| pagination | Pagination strategies |
| filtering-sorting | Query parameters design |
| versioning | API versioning approaches |
| Skill | Description |
|---|---|
| graphql-basics | GraphQL fundamentals |
| schema-design | Type system and schema |
| resolvers | Resolver patterns |
| mutations | Write operations |
| subscriptions | Real-time updates |
| Skill | Description |
|---|---|
| grpc-basics | gRPC fundamentals |
| protobuf | Protocol Buffers |
| streaming | Streaming patterns |
| Skill | Description |
|---|---|
| openapi-swagger | OpenAPI specification |
| api-documentation | Documentation best practices |
| examples | Code examples and SDKs |
| Skill | Description |
|---|---|
| request-response | Request/response design |
| error-handling | Error handling patterns |
| authentication | Auth patterns |
| rate-limiting | Rate limiting strategies |
| idempotency | Idempotent operations |
| Skill | Description |
|---|---|
| api-guidelines | General API guidelines |
| backwards-compatibility | Maintaining compatibility |
| api-evolution | Evolving APIs over time |