aj-geddes/rest-api-design

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