# Team Api Conventions

> API design conventions for this codebase. Use whenever writing or reviewing API endpoints, route handlers, or HTTP clients.

- **Type:** Skill
- **Install:** `agentstack add skill-davila7-claude-with-skills-claude-only-context`
- **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/02-intermediate/lesson-02-invocation-control/examples/claude-only-context
- **Website:** https://claude-with-skills.vercel.app

## Install

```sh
agentstack add skill-davila7-claude-with-skills-claude-only-context
```

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

## About

## Team API conventions

Apply these conventions whenever you write, review, or modify API endpoints, route handlers, request validation, or HTTP client code in this codebase.

### REST naming

- Use lowercase, hyphen-separated resource names in URLs: `/user-profiles`, not `/userProfiles` or `/user_profiles`.
- Resources are plural nouns: `/invoices`, `/line-items`, not `/invoice`, `/lineItem`.
- Nested resources express ownership: `/invoices/{id}/line-items`.
- Actions that do not map cleanly to CRUD use a verb suffix on the resource: `/invoices/{id}/send`, `/invoices/{id}/void`.
- Query parameters are camelCase: `?pageSize=20&startAfter=abc`.

### Response format

All API responses use a consistent envelope:

```json
{
  "data": {},
  "meta": {
    "requestId": "uuid",
    "timestamp": "ISO-8601"
  }
}
```

List responses add `pagination` to `meta`:

```json
{
  "data": [],
  "meta": {
    "requestId": "uuid",
    "timestamp": "ISO-8601",
    "pagination": {
      "total": 142,
      "pageSize": 20,
      "nextCursor": "opaque-string-or-null"
    }
  }
}
```

Do not return bare arrays or bare objects at the top level.

### Error format

```json
{
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "No invoice with id 'xyz' exists.",
    "requestId": "uuid"
  }
}
```

- `code` is SCREAMING_SNAKE_CASE and stable across releases. Client code switches on this value.
- `message` is human-readable and may change between releases.
- HTTP status codes: 400 for client errors, 401 for unauthenticated, 403 for unauthorized, 404 for not found, 409 for conflicts, 422 for validation failures, 500 for server errors. Do not use 200 with an error body.

### Versioning

- Version in the URL path: `/v1/invoices`, `/v2/invoices`.
- Never version individual endpoints separately. When a breaking change is needed, version the entire API surface together.
- Maintain at least one prior major version for six months after a new version is released.

### Authentication

- All authenticated requests use the header `Authorization: Bearer `.
- Never accept tokens as query parameters. Log warnings if a query parameter token is detected (it may have been sent by an older client).
- Service-to-service calls use `X-Service-Token` instead of `Authorization` and are validated differently at the gateway.

### When reviewing API code

Flag any of the following as review comments:
- Bare array or bare object response bodies
- Missing `requestId` in responses
- Error bodies that return 200 OK
- Tokens accepted via query parameters
- Inconsistent resource naming (mixed plural/singular, mixed casing)

## 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-claude-only-context
- 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%.