api-conventions

API Conventions

Load this skill when designing or implementing API endpoints. Each rule has a concrete example so reviewers can recognise the shape.

REST Conventions

• Resources are plural nouns. Actions live on HTTP methods, not in the path.

  GOOD:   GET    /users
          POST   /users
          GET    /users/42
          DELETE /users/42
  
  BAD:    GET    /getUser?id=42
          POST   /createUser
          GET    /user/delete?id=42       # never, ever
  

• HTTP methods map to actions. Pick one row and stick to it.

  Method	Semantics	Idempotent	Has body?
  GET	Read; no side effects	yes	no
  POST	Create (or non-idempotent action)	no	yes
  PUT	Full replace	yes	yes
  PATCH	Partial update	usually	yes
  DELETE	Remove	yes (here)	no

• Nested resources express ownership. One level deep is plenty.

  GOOD: GET /users/42/orders
  BAD:  GET /users/42/orders/17/items/3/refunds   # design smell — flatten to /refunds/{id}
  

Request / Response Shape

• All responses are JSON with Content-Type: application/json; charset=utf-8.

• Success responses include a data key:

  { "data": { "id": "usr_42", "email": "[email protected]" } }
  

• Error responses use this exact shape (top-level error object):

  { "error": { "code": "RESOURCE_NOT_FOUND", "message": "User 42 not found" } }
  

  Codes are SCREAMING_SNAKE_CASE strings (machine-readable). The message is human-readable but does not include stack traces, paths, or query fragments. See security-checklist#error-handling.

• Timestamps are ISO 8601 UTC with the Z suffix:

  GOOD: "2026-03-26T12:00:00Z"
  GOOD: "2026-03-26T12:00:00.123Z"
  BAD:  "2026-03-26 12:00:00"            # not ISO 8601
  BAD:  "2026-03-26T12:00:00+00:00"      # use Z for UTC, not +00:00
  BAD:  1711454400                        # Unix epoch — pick ISO and stick to it