engineering-rest-api-design
Persona: You are a senior API architect. Every endpoint you design is a contract — once published, it becomes someone else's dependency. Design for the consumer first, optimize for the maintainer second.
Modes:
- Design mode — designing new endpoints: apply conventions top-down, validate against checklist in
references/checklist.md. - Review mode — reviewing existing API contracts: audit naming, pagination, error envelope, idempotency, and async patterns against this skill's rules. Flag violations with severity (breaking / inconsistent / style).
- Document mode — writing API documentation: follow the spec template in
references/api-document-template.md.
REST API Design
Mindset
- Design first — think at the high level, cover edge cases on paper, reduce implementation cost.
- Scalable — endpoints should handle growth in consumers, data volume, and team size.
- Consistent — one convention across all services; deviation requires justification.
- Inspect every aspect — URL, method, headers, body, pagination, errors, async behavior.
- No one-size-fits-all — document trade-offs explicitly when deviating from conventions.
HTTP Methods
More from jimnguyendev/jimmy-skills
backend-go-testing
Provides a comprehensive guide for writing production-ready Golang tests. Covers table-driven tests, test suites with testify, mocks, unit tests, integration tests, benchmarks, code coverage, parallel tests, fuzzing, fixtures, goroutine leak detection with goleak, snapshot testing, memory leaks, CI with GitHub Actions, and idiomatic naming conventions. Use this whenever writing tests, asking about testing patterns or setting up CI for Go projects. Essential for ANY test-related conversation in Go.
14backend-go-code-style
Golang code style and readability conventions that require human judgment. Use when reviewing clarity, naming noise, file organization, package boundaries, comments, or maintainability tradeoffs in Go code. Do not use this for golangci-lint setup or lint output interpretation; use `jimmy-skills@backend-go-linter` for tooling.
12backend-go-safety
Defensive Golang coding to prevent panics, silent data corruption, and subtle runtime bugs. Use whenever writing or reviewing Go code that involves nil-prone types (pointers, interfaces, maps, slices, channels), numeric conversions, resource lifecycle (defer in loops), or defensive copying. Also triggers on questions about nil panics, append aliasing, map concurrent access, float comparison, or zero-value design.
11backend-go-design-patterns
Idiomatic Golang design patterns for real backend code: constructors, error flow, dependency injection, resource lifecycle, resilience, data handling, and package boundaries. Apply when designing Go APIs, structuring packages, choosing between patterns, making architecture decisions, or hardening production behavior. Default to simple, feature-first designs unless complexity has clearly appeared.
11backend-go-grpc
Provides gRPC usage guidelines, protobuf organization, and production-ready patterns for Golang microservices. Use when implementing, reviewing, or debugging gRPC servers/clients, writing proto files, setting up interceptors, handling gRPC errors with status codes, configuring TLS/mTLS, testing with bufconn, or working with streaming RPCs.
11backend-go-cli
Golang CLI application development. Use when building, modifying, or reviewing a Go CLI tool — especially for command structure, flag handling, configuration layering, version embedding, exit codes, I/O patterns, signal handling, shell completion, argument validation, and CLI unit testing. Also triggers when code uses cobra, viper, or urfave/cli.
10