Stats
Actions
Tags
From f5-core
Provides API design principles, comparisons, and best practices for REST, GraphQL, gRPC including resource naming, schema design, documentation with OpenAPI, versioning, and error handling.
How this skill is triggered — by the user, by Claude, or both
Slash command
/f5-core:api-designThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
API design knowledge for building clean, consistent, and developer-friendly APIs.
best-practices/api-evolution.mdbest-practices/api-guidelines.mdbest-practices/backwards-compatibility.mddocumentation/api-documentation.mddocumentation/examples.mddocumentation/openapi-swagger.mdgraphql/graphql-basics.mdgraphql/mutations.mdgraphql/resolvers.mdgraphql/schema-design.mdgraphql/subscriptions.mdgrpc/grpc-basics.mdgrpc/protobuf.mdgrpc/streaming.mdpatterns/authentication.mdpatterns/error-handling.mdpatterns/idempotency.mdpatterns/rate-limiting.mdpatterns/request-response.mdreferences/documentation.mdAPI 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 |
npx claudepluginhub fujigo-software/f5-framework-claude --plugin f5-coreGuides API design by comparing REST, GraphQL, and gRPC; covers protocol selection, resource modeling, endpoint patterns, and best practices for developer experience.
Guides REST and GraphQL API design with principles for intuitive, scalable, maintainable APIs. Use for designing new APIs, refactoring, standards, reviews, and documentation.
Provides decision trees, patterns, and guidance for REST, gRPC, GraphQL API design including resource naming, schema, versioning, pagination, rate limiting, auth, and OpenAPI.