rest-api-design

SKILL.md

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