rest-api-design

name: rest-api-design description: > Design RESTful APIs following best practices for resource modeling, HTTP methods, status codes, versioning, and documentation. Use when creating new APIs, designing endpoints, or improving existing API architecture.

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:

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 versioning