Api design
Design REST or GraphQL APIs: resource modeling, URL conventions, error contracts, versioning, pagination, idempotency keys, rate-limit headers. Use when creating a new API endpoint or reviewing API consistency.From its SKILL.md
npx -y skills add youcisla/Agent-Foundry --skill api-designAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its file declares
Copied from the file, not written here
The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
1.8 KB, as published. Nobody here has run it
API Design
Design APIs that are predictable, versionable, and self-documenting.
REST Conventions
- Resources are nouns, plural:
/users,/cases,/reflections - Actions are sub-resources:
/users/{id}/sessions - Verbs only when nothing else fits:
/users/{id}/verify-email
HTTP Methods
| Method | Action | Idempotent |
|---|---|---|
| GET | examine | Yes |
| POST | Create | No (without key) |
| PUT | Replace | Yes |
| PATCH | Partial update | No |
| DELETE | Delete | Yes |
Status Codes
| Code | When |
|---|---|
| 200 | Successful read/update |
| 201 | Successful create (include Location) |
| 204 | Successful delete / no body |
| 400 | Malformed request |
| 401 | Missing/invalid auth |
| 403 | Not permitted |
| 404 | Resource missing or hidden |
| 409 | State collision |
| 422 | Valid syntax, semantic fail |
| 429 | Rate-limited (Retry-After) |
| 500 | Unexpected server error |
Error Contract
Every error uses the same shape:
{
"error": {
"code": "user_not_found",
"message": "No user with id 'abc123'",
"param": "user_id",
"doc_url": "https://api.example.com/docs/errors#user_not_found"
}
}
code: stable, snake_case, machine-readablemessage: human-readable, may include the failing valueparam: which field caused the issuedoc_url: always present for documented codes
Anti-patterns
- Skipping verification when the change 'feels small'
- Reasoning by analogy without a real example