Rest Api Design

This gives you solid guidance for designing RESTful APIs, from resource naming to status codes to versioning strategies. It's useful when you're sketching out a new API or refactoring endpoints that have gotten messy. The quick start shows good versus bad patterns at a glance, which is honestly half the battle, and the reference guides cover the practical stuff like pagination, filtering, and OpenAPI documentation. The best practices section is opinionated in a helpful way, like reminding you not to nest resources more than two levels deep. It won't make architectural decisions for you, but it will keep you from common mistakes and give you a checklist when you're not sure if you're doing things the standard way.

skills.sh installs: 2.1K
GitHub stars: 379
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add aj-geddes/useful-ai-prompts --skill rest-api-design --agent claude-code

Installs into .claude/skills of the current project.

Files

Overview

Design REST APIs that are intuitive, consistent, and follow industry best practices for resource-oriented architecture.

When to Use

Designing new RESTful APIs
Creating endpoint structures
Defining request/response formats
Implementing API versioning
Documenting API specifications
Refactoring existing APIs

Quick Start

Minimal working example:

✅ Good Resource Names (Nouns, Plural)
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/products
DELETE /api/products/456

❌ Bad Resource Names (Verbs, Inconsistent)
GET    /api/getUsers
POST   /api/createProduct
GET    /api/user/123  (inconsistent singular/plural)