ClaudeChatGPTCopilotDeveloper & CodeIntermediate

RESTful API Design (Best Practices)

Design clean, well-documented REST APIs with proper resource naming, HTTP methods, status codes, pagination, and error handling.

Updated June 2026

restful-api-design-best-practices.txt

Copy & Download at the bottom ↓

You are a software architect specialized in REST API design. You know that a well-designed API: (1) is intuitive — a dev understands it without reading the documentation, (2) is consistent — all endpoints follow the same pattern, (3) is resilient — errors are handled predictably, (4) is evolvable — it can grow without breaking changes. You follow industry standards (JSON:API, OpenAPI) when they make sense.

Design the RESTful API for:

**Product:** [describe the application]
**Main resources:** [e.g.: users, products, orders, payments]
**Operations:** [basic CRUD, custom operations]
**Authentication:** [JWT, API Key, OAuth — or recommend]
**API audience:** [internal, clients, partners, public]
**Stack:** [Node.js, Python, Go — affects code examples]
**Database:** [PostgreSQL, MongoDB, MySQL]

Deliver:

**1. Naming and conventions**
- Base URL: recommended format
- Versioning: /v1/, header, or query param
- Resources: plural, lowercase, kebab-case
- Examples of good vs bad names

**2. Complete endpoints**
For each resource, all endpoints:
GET    /v1/resources          — List (with pagination)
GET    /v1/resources/:id      — Detail
POST   /v1/resources          — Create
PUT    /v1/resources/:id      — Update (full)
PATCH  /v1/resources/:id      — Update (partial)
DELETE /v1/resources/:id      — Remove

For each endpoint: URL, method, request/response body, status codes, query params.

**3. Standardized error handling**
Consistent format with code, message, details.

**4. Pagination**
Cursor-based or offset with metadata.

**5. Filters and sorting**
Standard pattern for filtering and sorting results.

**6. Authentication and authorization**
Recommended method + implementation + rate limiting.

**7. Additional best practices**
Idempotency, CORS, Compression, Cache headers.

**8. Documentation (OpenAPI spec)**
Example OpenAPI/Swagger specification.

When to Use

When designing a new API from scratch

To standardize existing APIs that grew without design

When documenting APIs for team or clients

In code reviews of new endpoints

How to Use This Prompt

Copy the prompt below into Claude or ChatGPT

Describe the API resources and operations

Receive the complete design with endpoints and examples

Implement following the specifications

Example Input

Product: Clothing e-commerce (API for mobile app + admin)
Resources: products, categories, orders, users, reviews
Stack: Node.js + PostgreSQL
Auth: JWT

Expected Output

**GET /v1/products**
Query: ?category=camisetas&min_price=50&max_price=200&sort=-created_at&page=1&per_page=20

Response 200:
{
  "data": [
    {
      "id": "prod_abc123",
      "name": "Basic Cotton T-Shirt",
      "slug": "basic-cotton-t-shirt",
      "price": 79.90,
      "category": { "id": "cat_xyz", "name": "T-Shirts" },
      "images": ["https://..."],
      "in_stock": true,
      "created_at": "2025-03-15T10:30:00Z"
    }
  ],
  "meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 }
}

Error 404:
{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product with ID 'prod_xyz' not found.",
    "status": 404
  }
}

RESTful API Design (Best Practices)

When to Use

How to Use This Prompt

Example Input

Expected Output

Ready to use this prompt?