agentleFS
Sign inStart free
KbWenKbWen/agent-virtual-office/.agents/skills/api-design/SKILL.md

api-design

Skill65 starsChanged 3 months agoMITView on GitHub

Design or review REST/GraphQL APIs when endpoints or contracts change.

We split this skill into the rules it gives an agent

2 rules. 0 are common, 0 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 164 edited versions we read keep these.

  • 0

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use nouns for resources, not verbs: GET /users not GET /getUsers

    line 21
  2. Very specific:

    Use kebab-case for multi-word paths: /order-items

    line 24

“Common” is measured: kept by at least 6 in 10 of the 164 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- This is a SCAFFOLD skill -->

API Design

When to Apply

  • Classification: feature, architecture-change, hotfix (if touching API endpoints)
  • Phase: /implement (design & build), /review (compliance check), /test (contract verification)
  • Trigger: Task involves creating, modifying, or deprecating API endpoints

Conventions

Customize after /app-init: Replace these generic conventions with your project's ADR decisions.

Endpoint Naming

  • Use nouns for resources, not verbs: GET /users not GET /getUsers
  • Plural resource names: /users, /orders, /products
  • Nested resources for relationships: /users/:id/orders
  • Use kebab-case for multi-word paths: /order-items

HTTP Methods

ActionMethodSuccess StatusIdempotent
ListGET200Yes
Get oneGET200Yes
CreatePOST201No
Full updatePUT200Yes
Partial updatePATCH200No
DeleteDELETE204Yes

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": {
      "field": "email",
      "constraint": "required"
    }
  }
}

Standard Error Codes

HTTP StatusWhenError Code Pattern
400Invalid inputVALIDATION_ERROR, INVALID_FORMAT
401Not authenticatedUNAUTHORIZED
403Not permittedFORBIDDEN
404Resource not foundNOT_FOUND
409Conflict (duplicate)CONFLICT, DUPLICATE
422Business rule violationUNPROCESSABLE
429Rate limitedRATE_LIMITED
500Server errorINTERNAL_ERROR

Pagination

{
  "data": [...],
  "pagination": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "has_next": true
  }
}

Versioning

  • URL path versioning: /api/v1/users
  • Breaking changes require new version
  • Deprecation: add Sunset header with date, keep old version for N months

Input Validation

  • Validate at the controller/route level BEFORE business logic
  • Return ALL validation errors at once (batch), not one at a time
  • Sanitize strings: trim whitespace, escape HTML where applicable
  • Enforce max lengths on all string fields

Checklist

During /implement:

  • Every endpoint has input validation
  • Every endpoint returns consistent error format
  • Every endpoint has proper auth check (or explicit public annotation)
  • Pagination for list endpoints
  • Rate limiting consideration (at least documented in spec)
  • No sensitive data in URL parameters (use body or headers)
  • Request/response examples in spec match implementation

During /review:

  • No N+1 query patterns in list endpoints
  • Proper HTTP status codes (not everything is 200)
  • Idempotency for PUT/DELETE
  • Error messages don't leak internal details (stack traces, SQL, paths)
  • CORS configured per ADR policy

Heading-Scoped Read Note

For phase-entry loading, read only:

  • When to Apply
  • Checklist

Load Conventions, Anti-Patterns, and References on full read or cache miss only.

Anti-Patterns

  • God endpoint: One endpoint that does everything based on query params. Split into specific endpoints.
  • Verb in URL: POST /createUser → POST /users
  • Inconsistent naming: Mixing /user and /products (singular vs plural)
  • Swallowing errors: Catching exceptions and returning 200 with { success: false }
  • Leaking internals: Returning DB column names directly as API fields without mapping
  • Missing 404: Returning empty 200 instead of 404 when resource doesn't exist
  • Unbounded lists: List endpoints without pagination or default limits

References

  • Project ADR: docs/adr/ADR-002-project-architecture.md § API Design
  • Security guardrails: .agent/rules/security_guardrails.md (A01: Access Control, A03: Injection)
  • Spec template: .agentcortex/templates/spec-app-feature.md § API Contract

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free