# REST API

> Provides REST API design and implementation standards. Ensures proper URL structure, pagination, sorting, filtering, and error handling patterns. Specializes in RESTful principles, HTTP method semantics, status code usage, versioning strategies, HATEOAS, and API documentation. Implements consistent response structures and content negotiation. Use when: designing REST API endpoints, defining URL structures and naming conventions, implementing pagination/sorting/filtering, choosing appropriate HTTP methods (GET/POST/PUT/PATCH/DELETE), selecting HTTP status codes, designing request/response schemas, handling API errors and validation, implementing API versioning, documenting APIs with OpenAPI/Swagger, or designing hypermedia controls (HATEOAS).

- Skill: `majiayu000/rest-api-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/rest-api-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/rest-api-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/rest-api-2

---


# REST API Design Standards

## Naming Conventions

### Field Naming

- Boolean: Require `is/has/can` prefix
- Date: Require `~At` suffix
- Use consistent terminology throughout the project (unify on either "create" or "add")

## Date Format

- ISO 8601 UTC
- Use DateTime type

## Pagination

### Cursor-Based (Industry Standard)

- Parameters: `?cursor=xyz&limit=20`
- Response: `{ data: [...], nextCursor: "abc", hasNext: true }`

## Sorting

- `?sortBy=createdAt&sortOrder=desc`
- Support multiple sort
- Specify defaults

## Filtering

- Range: `{ min, max }` or `{ gte, lte }`
- Complex conditions use nested objects

## URL Structure

### Nested Resources

- Maximum 2 levels

### Actions

- Allow verbs only when unable to represent as resource
- `/users/:id/activate`

## Response

### List

- `data` + pagination info

### Creation

- 201 + resource (excluding sensitive information)

### Error (RFC 7807 ProblemDetail)

- Required: `type`, `title`, `status`, `detail`, `instance`
- Optional: `errors` array

## Batch

- `/batch` suffix
- Success/failure count + results