# API Conventions

> Universal REST API design principles — response envelope, route naming, versioning, pagination, status codes. Applies to any backend language or framework. Load when designing or implementing any API endpoint. Use when this capability is needed.

- Skill: `tomevault-io/api-conventions-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/api-conventions-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/api-conventions-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/api-conventions-3

---


Full standards in [api-conventions.md](api-conventions.md). Always-on summary:

**Response envelope — always consistent:**
- Success: `{ "success": true, "data": <resource>, "meta": { "requestId": "...", "timestamp": "..." } }`
- Success + pagination: add `"pagination": { "nextCursor": "...", "total": N, "limit": 20, "hasMore": true }`
- Error: `{ "success": false, "error": { "code": "NOT_FOUND", "message": "...", "details": [...] }, "meta": { ... } }`

**JS implementation shape (always use this):**
```ts
// Success
res.json({ success: true, data: result });
// Error
res.json({ success: false, error: { code: 'NOT_FOUND', message: '...' } });
```

**Routes:**
- Prefix and version from day one: `/api/v1/`
- Plural nouns: `/orders` not `/order` or `/getOrders`
- Nested for ownership: `/users/:userId/orders` (max 2 levels deep)
- kebab-case path segments: `/order-items` not `/orderItems`

**HTTP status codes:**
- `200` success · `201` created · `204` deleted (no body)
- `400` invalid input · `401` not authenticated · `403` not authorised
- `404` not found · `409` conflict · `422` business rule violated · `500` unexpected

**Pagination:** prefer cursor-based (`?limit=20&cursor=<id>`) over offset — offset is inconsistent under concurrent writes

**Never:** verb routes (`/getOrders`), unversioned paths (`/api/orders`), bare arrays at root, `200` for errors

**For implementation helpers** (response builder functions, validation middleware, framework-specific wiring), see your backend layer skill.

---
> Source: [manikumarkv/devrunway-claude-plugin](https://github.com/manikumarkv/devrunway-claude-plugin) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->