# rest-api-design-patterns

A reference skill for designing REST APIs: resource modeling, versioning, pagination, HATEOAS and HTTP method semantics.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 525 installs · ★ 62
- Author: manutej
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/manutej/luxor-claude-marketplace/tree/HEAD/plugins/luxor-backend-toolkit/skills/rest-api-design-patterns/SKILL.md
- Updated: 2026-06-13
- HTML: https://affpapa.org/en/nevibecode/skills/rest-api-design-patterns

## What it does

The skill hands your agent a set of rules and worked examples for designing and refactoring REST APIs. It covers resource naming, nested endpoints, query-parameter filtering, bulk operations, and HTTP methods with FastAPI and Express.js samples. There is also the Richardson maturity model, from a single URI with POST up to hypermedia controls.

Use it when you start an API from scratch or want an existing one to look consistent. The agent will tell you where a collection ends and an item begins, why `GET /getUsers` is a bad route, and how to avoid five levels of nesting. Separate sections deal with versioning, error handling and OpenAPI docs.

The skill is plain text — instructions for the agent, not a library. It installs into Claude, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode, each with its own command and its own `SKILL.md` path. GitHub Copilot needs a `gh` build that supports skills, otherwise the install command fails.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add manutej/luxor-claude-marketplace --skill rest-api-design-patterns -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/rest-api-design-patterns/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/rest-api-design-patterns/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add manutej/luxor-claude-marketplace --skill rest-api-design-patterns -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/rest-api-design-patterns/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add manutej/luxor-claude-marketplace --skill rest-api-design-patterns -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/rest-api-design-patterns/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install manutej/luxor-claude-marketplace rest-api-design-patterns
```

2. **Manually: put the files in place**
- File: `.github/skills/rest-api-design-patterns/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add manutej/luxor-claude-marketplace --skill rest-api-design-patterns -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/manutej/luxor-claude-marketplace --path plugins/luxor-backend-toolkit/skills/rest-api-design-patterns
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/rest-api-design-patterns/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add manutej/luxor-claude-marketplace --skill rest-api-design-patterns -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/manutej/luxor-claude-marketplace/tree/HEAD/plugins/luxor-backend-toolkit/skills/rest-api-design-patterns/SKILL.md

## When to use it
- model resources and endpoints for a new REST API
- rewrite existing routes to use proper HTTP methods
- add versioning without breaking current clients
- set up pagination, filtering and sorting on collections
- document the API in OpenAPI and map errors to status codes

## Example prompts
- Design a REST API for orders: resources, endpoints, response codes
- Review my routes against REST conventions — flag bad naming and methods
- Add versioning and pagination to my FastAPI API

## Similar
- [rest-api-design](https://affpapa.org/en/nevibecode/skills/rest-api-design.md) — skill · 2100 installs
- [api-design](https://affpapa.org/en/nevibecode/skills/agent-skills-team-api-design.md) — skill · 387 installs
- [agentmemory-rest-api](https://affpapa.org/en/nevibecode/skills/agentmemory-rest-api.md) — skill · 10800 installs
- [public-api-design-review](https://affpapa.org/en/nevibecode/skills/public-api-design-review.md) — skill · 7800 installs
- [api-design-patterns](https://affpapa.org/en/nevibecode/skills/api-design-patterns.md) — skill · 929 installs
- [wp-rest-api](https://affpapa.org/en/nevibecode/skills/wp-rest-api.md) — skill · 5900 installs

From the same set: [manutej/luxor-claude-marketplace](https://affpapa.org/en/nevibecode/by/manutej/luxor-claude-marketplace.md) — 31 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md