api-design — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited api-design (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
When NOT to use:
When invoked by name, announce: "Using api-design to guide API design decisions."
These apply regardless of REST or GraphQL:
Write the contract (OpenAPI spec or GraphQL schema) before implementation. Code-first is the normal workflow for frameworks like FastAPI that generate the contract from code, and is acceptable for rapid prototypes or internal tools with stable requirements. The choice is driven by governance needs, not protocol correctness.
Pick conventions and apply them uniformly across every endpoint, field, and error response.
Never mirror internal data models in public contracts. Abstract so you can change internals without breaking clients. See rest-design.md § API Surface Is Not Database Surface for rationale, anti-patterns, and decoupling strategies.
Enforce input constraints and response shaping at the API boundary. Authenticate before business logic runs. As a strong default, keep fine-grained authorization policy in the domain/business layer — but coarse access control (e.g., "only authenticated users") is legitimately enforced in gateways or middleware before the domain layer.
Hyrum's Law: with enough users, every observable behavior of your API — including undocumented quirks, error message text, and field ordering — becomes a de facto contract someone depends on. Design with that in mind: be intentional about what you expose, and treat any change as potentially breaking until proven otherwise. Additive changes are usually safe, but verify compatibility against clients — adding a GraphQL enum value is schema-safe yet can surprise clients that assume exhaustive handling. Removal, renaming, and type changes require versioning (REST) or deprecation workflows (GraphQL).
HTTPS, authentication, authorization, rate limiting, and input validation are not optional additions — they are part of the design.
Use the references below as scoped guidance. Some references describe broad consensus, while others document strong defaults or ecosystem-specific patterns.
| Design Task | Reference | When to Load |
|---|---|---|
| REST vs GraphQL decision | rest-vs-graphql.md | Starting a new API or evaluating a paradigm shift |
| REST endpoint design | rest-design.md | Designing REST resources, methods, status codes |
| GraphQL schema/query/mutation design | graphql-design.md | Designing GraphQL types, queries, mutations, subscriptions |
| URI/URL naming | uri-design.md | Naming endpoints, path segments, query parameters |
| API versioning | versioning.md | Planning version strategy, deprecation, migration |
| Error responses | error-handling.md | Designing error formats, status code usage, RFC 9457 |
| Pagination and filtering | pagination-filtering.md | Lists, collections, search results, sorting |
| FastAPI implementation | fastapi-practices.md | Building APIs with FastAPI specifically |
How to use this table: Load only the references relevant to the current task. For a new API design, start with rest-vs-graphql.md, then load the paradigm-specific reference. For targeted questions (e.g., "how should we version this?"), load only that reference.
REST requires careful endpoint design to avoid N+1 orchestration.
For the full decision tree and tradeoff matrix, load rest-vs-graphql.md.
| Mistake | Fix |
|---|---|
Verbs in REST URIs (/getUsers, /createOrder) | Use nouns + HTTP methods for CRUD; verbs only for controller resources (POST /orders/{id}/cancel) |
| Exposing database IDs/structure in API | Abstract with slugs, UUIDs, and domain-oriented shapes; use a mapping layer, not auto-serialization |
| Inconsistent error formats across endpoints | Define one error schema, use it everywhere |
| No pagination on collection endpoints | Paginate unbounded or growth-prone collections; small bounded reference data may not need it — always set default and max page sizes when pagination is used |
| Breaking changes without versioning | Use additive changes; version when breaking is unavoidable |
Generic GraphQL mutations (updateEntity) | Use specific semantic mutations (publishPost, archiveOrder) |
| Auth logic in resolvers/handlers instead of business layer | Delegate authorization to domain services |
| Nullable everything / non-null everything | Be intentional: non-null only when you can guarantee presence |
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.