# Api Conventions

> REST API design conventions for this codebase. Use when writing or reviewing API endpoints, route definitions, response formatting, or client code that calls the API.

- **Type:** Skill
- **Install:** `agentstack add skill-davila7-claude-with-skills-api-conventions`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [davila7](https://agentstack.voostack.com/s/davila7)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [davila7](https://github.com/davila7)
- **Source:** https://github.com/davila7/claude-with-skills/tree/main/src/content/docs/03-advanced/lesson-04-subagent-uses-skills/examples/api-developer/.claude/skills/api-conventions
- **Website:** https://claude-with-skills.vercel.app

## Install

```sh
agentstack add skill-davila7-claude-with-skills-api-conventions
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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:

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

For list responses, `meta` also includes pagination fields:

```json
{
  "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:

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

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

```json
{
  "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](https://github.com/davila7)
- **Source:** [davila7/claude-with-skills](https://github.com/davila7/claude-with-skills)
- **License:** MIT
- **Homepage:** https://claude-with-skills.vercel.app

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-davila7-claude-with-skills-api-conventions
- Seller: https://agentstack.voostack.com/s/davila7
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.