back
loading skill details...
>
REST API Design
Table of Contents
Overview
When to Use
Quick Start
Reference Guides
Best Practices
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)
Reference Guides
Detailed implementations in the references/ directory:
Guide
Contents
Resource Naming
Resource Naming, HTTP Methods & Operations
Request Examples
Request Examples
Query Parameters
Query Parameters
Response Formats
Response Formats
HTTP Status Codes
HTTP Status Codes, API Versioning, Authentication & Security, Rate Limiting Headers
OpenAPI Documentation
OpenAPI Documentation
Complete Example: Express.js
const express = require("express");
Best Practices
✅ DO
Use nouns for resources, not verbs
Use plural names for collections
Be consistent with naming conventions
Return appropriate HTTP status codes
Include pagination for collections
Provide filtering and sorting options
Version your API
Document thoroughly with OpenAPI
Use HTTPS
Implement rate limiting
Provide clear error messages
Use ISO 8601 for dates
❌ DON'T
Use verbs in endpoint names
Return 200 for errors
Expose internal IDs unnecessarily
Over-nest resources (max 2 levels)
Use inconsistent naming
Forget authentication
Return sensitive data
Break backward compatibility without versioningdon't have the plugin yet? install it then click "run inline in claude" again.