api-design
by affaan-mapi-design is a REST API design skill for planning and reviewing endpoints, resource naming, status codes, pagination, filtering, versioning, and error responses.
This skill scores 83/100, which means it is a solid directory listing for users who want a focused REST API design reference with enough procedural guidance to be immediately useful. The repository gives clear activation cues, concrete design conventions, and practical examples, so agents should be able to trigger and apply it with less guesswork than a generic prompt.
- Explicit when-to-activate guidance covers endpoint design, API review, pagination/filtering, error handling, and versioning.
- Strong operational detail with concrete REST examples for URL structure, naming rules, methods, and status codes.
- Substantial body content with no placeholder markers, suggesting real workflow guidance rather than a stub.
- No install command or companion resources, so users must adopt it directly from the SKILL.md content.
- Evidence of workflow is present, but support files are minimal, which may limit coverage for edge cases or deeper implementation patterns.
Overview of api-design skill
What the api-design skill does
The api-design skill is a focused REST API design guide for turning vague endpoint ideas into cleaner, more consistent API contracts. It covers the parts teams usually get wrong first: resource naming, URL structure, HTTP method semantics, status codes, pagination, filtering, error responses, versioning, and rate limiting.
Who should install this api-design skill
This api-design skill fits backend engineers, platform teams, technical leads, and AI-assisted developers who need fast design help before writing controllers or OpenAPI specs. It is especially useful when creating public, partner, or shared internal APIs where consistency matters more than just “making it work.”
What job it helps you get done
The real job-to-be-done is not just “design an endpoint.” It is to make API decisions that remain understandable across docs, code reviews, client SDKs, and future versions. Compared with a generic prompt, api-design gives you an opinionated checklist for REST conventions, which reduces design drift and avoidable breaking changes.
Main limits and differentiators
Its strength is practical convention-setting, not framework-specific implementation. It is strongest for REST-style API Development, especially contract review and endpoint planning. It is a weaker fit for GraphQL, event-driven APIs, or deeply domain-specific protocol design where generic REST patterns are not the main problem.
How to Use api-design skill
Install context and where to read first
This repository exposes the skill primarily through skills/api-design/SKILL.md. There are no extra resources/, rules/, or helper scripts, so most of the value is in reading and applying that single file carefully. If you install from the parent repo, use the repo’s standard skill installation flow, then open SKILL.md first because that is where the activation cues and design patterns live.
What input the api-design skill needs
The api-design skill works best when you provide concrete API context, not just “design me a REST API.” Include:
- business entities:
users,orders,subscriptions - main operations: create, list, update, cancel, archive
- consumer type: internal app, third-party developers, mobile clients
- constraints: backward compatibility, auth model, pagination size, rate limits
- output format wanted: endpoint list, review notes, naming critique, error schema
A weak prompt:
- “Design an API for orders.”
A stronger prompt:
- “Use the api-design skill to design a REST API for order management. We need list/create/get/update/cancel endpoints, cursor pagination, filtering by status and date range, standardized error responses, and versioning guidance for a public API used by partners.”
How to turn a rough goal into a useful prompt
For best api-design usage, ask for decisions, not only examples. A good structure is:
- domain and users
- resources and relationships
- required operations
- constraints and edge cases
- preferred deliverable
Example:
- “Apply the api-design skill to review our draft API. Resources: users, orders, refunds. Relationships: users own orders; orders may have refunds. We need naming cleanup, status code recommendations, pagination and filtering conventions, and guidance on whether
cancelshould be a sub-resource or action endpoint.”
This improves output quality because the skill can map your domain onto its built-in REST patterns instead of guessing your model.
Suggested workflow for api-design for API Development
Use this workflow:
- Start with
SKILL.mdand scan the sections on activation, resource design, naming rules, methods, and status codes. - Draft your resources first, before debating payload fields.
- Ask the model to propose URLs and methods for each resource.
- Then request consistency checks for pagination, filtering, errors, versioning, and rate limiting.
- Finally, ask it to review for non-REST drift such as verbs in URLs, singular resource names, or inconsistent nested paths.
This order matters: teams often overfocus on schema details before fixing the contract shape.
api-design skill FAQ
Is this api-design skill better than a normal prompt?
Usually yes, if your problem is API contract quality rather than raw implementation. A normal prompt may generate plausible endpoints, but the api-design skill gives you a more repeatable REST lens: plural nouns, clean nested resources, method semantics, and consistent error/versioning decisions.
Is api-design install worth it for beginners?
Yes, if you already know basic HTTP and want guardrails. The skill is readable and example-heavy, so it helps beginners avoid common mistakes like verbs in URLs or mismatched status codes. It will not replace learning API fundamentals, but it shortens review cycles.
When is api-design a poor fit?
Skip it if you need GraphQL schema design, gRPC contracts, webhook event architecture, or framework-specific code generation. This skill is centered on REST conventions, so it is most useful when URL design and HTTP behavior are core decisions.
Can I use api-design for reviewing existing APIs?
Yes. In fact, that is one of the strongest uses. Give the current endpoints and ask for a contract review focused on naming, consistency, pagination, filtering, error handling, and versioning risks. It is often more valuable as a review tool than as a greenfield generator.
How to Improve api-design skill
Give the api-design skill better design inputs
The fastest way to improve results is to provide domain relationships and lifecycle rules. For example, saying “orders can be canceled only before fulfillment” helps the skill recommend whether POST /orders/:id/cancel is justified versus a normal status update. Domain rules produce better endpoint shapes than generic CRUD requests.
Watch for common failure modes
Common issues when using api-design:
- asking for endpoints without naming your resources clearly
- mixing implementation details with contract design too early
- forgetting client needs like pagination, filtering, or sorting
- accepting nested URLs that imply ownership when the relationship is looser
If the first draft looks messy, ask the model to justify every endpoint against REST conventions in the skill.
Iterate on output, don’t accept first-pass endpoints
A good second-round prompt is:
- “Re-check this API using the api-design skill. Flag non-idempotent operations, inconsistent pluralization, weak status code choices, and places where query parameters should replace custom endpoints.”
This kind of critique pass usually adds more value than requesting another full rewrite.
Use the skill as a contract review checklist
For stronger api-design guide workflows, use the skill in review mode before implementation:
- resource names and URL patterns
- method semantics and idempotency
- pagination/filtering defaults
- error response structure
- versioning and rate-limit exposure
That keeps API Development aligned across teams and makes the skill more than a one-time prompt enhancer.