Openagentskills Betterskills REST API Design

REST API Design

Resource naming

• Nouns, plural collections: /users, /users/{id}/orders
• Actions as sub-resources when not CRUD: /users/{id}/activate (prefer state change via PATCH)
• Kebab-case paths; lowercase

HTTP methods

Status codes (defaults)

Error body (consistent shape)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable summary",
    "details": [{ "field": "email", "issue": "invalid format" }]
  }
}

Pagination

Prefer cursor-based for large sets:

{
  "data": [],
  "next_cursor": "opaque-token",
  "has_more": true
}

Offset acceptable for admin or small tables; document limits (limit max 100).

Versioning

• URL prefix (/v1/) or header (Accept: application/vnd.company.v1+json)
• Never break clients without a new version or deprecation window

Review checklist

• Consistent naming and pluralization
• Correct status codes (not 200 for errors)
• Filtering/sorting documented
• Auth on every mutating route
• Idempotency keys for POST payments/bookings where needed

Source: openagentskills/betterskills — distributed by TomeVault.