Api Conventions

These conventions apply to every API endpoint in this codebase. Follow them exactly. If a new situation requires deviation, document the reason in a code comment.

URL structure

Pattern: /api/v{major}/{resource}

• Resource names are plural nouns in kebab-case: /api/v1/users, /api/v1/billing-accounts
• Nested resources use path segments: /api/v1/users/{id}/sessions
• Do not use verbs in URLs: use /api/v1/users/{id} with DELETE, not /api/v1/delete-user/{id}
• Query parameters are kebab-case: ?page-size=20&sort-by=created-at

HTTP methods

| Method | Meaning | Success status | |--------|---------|----------------| | GET | Retrieve resource(s), no side effects | 200 | | POST | Create a new resource | 201 | | PUT | Replace a resource entirely | 200 | | PATCH | Partially update a resource | 200 | | DELETE | Delete a resource | 204 (no body) |

Use GET for all read operations. Do not use POST for reads.

Response envelope

All successful responses (except 204) use this envelope:

{
  "data": ,
  "meta": {
    "timestamp": "",
    "version": ""
  }
}

For list responses, meta also includes pagination fields:

{
  "data": [...],
  "meta": {
    "timestamp": "2024-11-01T14:30:00Z",
    "version": "1.4",
    "next_cursor": "",
    "limit": 20,
    "count": 20
  }
}

count is the number of items in the current page, not the total across all pages. Do not include a total count unless explicitly required, as it forces an expensive COUNT query.

Error format

All error responses use this envelope:

{
  "error": {
    "code": "SNAKE_CASE_ERROR_CODE",
    "message": "Human-readable description safe for end users.",
    "details": {}
  }
}

• code is a stable machine-readable identifier in SCREAMINGSNAKECASE
• message is safe for end users — do not include stack traces, SQL, or internal paths
• details carries structured field-level information for validation errors:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "One or more fields failed validation.",
    "details": {
      "fields": [
        { "field": "email", "message": "Must be a valid email address." },
        { "field": "birth_date", "message": "Must be in the past." }
      ]
    }
  }
}

Status codes

| Code | Use | |------|-----| | 200 | Successful GET, PUT, PATCH | | 201 | Successful POST (resource created) | | 204 | Successful DELETE (no body) | | 400 | Malformed request (bad JSON, wrong content-type) | | 401 | Not authenticated — missing or invalid token | | 403 | Authenticated but not authorized for this resource | | 404 | Resource not found | | 409 | Conflict — resource already exists, optimistic lock conflict | | 422 | Validation failed — request is well-formed but semantically invalid | | 429 | Rate limited — include Retry-After header | | 500 | Unexpected server error | | 503 | Service temporarily unavailable — include Retry-After header |

Do not use 400 for validation errors — use 422. Do not use 500 for expected error cases that have a more specific code.

Authentication

All protected endpoints require a Bearer token in the Authorization header:

Authorization: Bearer 

The token is validated by the auth middleware before the handler runs. Handlers do not validate tokens directly. If the middleware passes, request.user (or the framework equivalent) is populated with the authenticated user's identity.

Pagination

Use cursor-based pagination, not offset-based.

Request parameters:

• cursor: opaque cursor string from the previous page's next_cursor (absent on first page)
• limit: number of items to return, default 20, maximum 100

Response meta fields:

• next_cursor: cursor to pass for the next page, or null if this is the last page
• limit: the limit used for this page
• count: number of items returned in this page

Do not expose integer offsets or page numbers in the public API.

Versioning

• Major version in the URL path: /api/v1/, /api/v2/
• Minor version in the response header: X-API-Version: 1.4
• Breaking changes require a new major version
• Additive changes (new fields, new endpoints) increment the minor version
• Deprecated fields are kept for at least two minor versions before removal

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: davila7
• Source: davila7/claude-with-skills
• License: MIT
• Homepage: https://claude-with-skills.vercel.app

Install and usage instructions live in the source repository linked above.