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:

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 versioning