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.
npx claudepluginhub fujigo-software/f5-framework-claude --plugin f5-coreThis skill is limited to using the following tools:
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.mdGuides 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.
Applies REST and GraphQL API design principles for intuitive, scalable APIs. Use when designing new APIs, reviewing specifications, refactoring, or establishing standards.
Share bugs, ideas, or general feedback.
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 |