api-design

name	api-design
description	Guide for designing and documenting RESTful APIs. Use when asked to design an API, create endpoints, or document an API.
source	Internal engineering practices, REST API conventions
domain	architecture
level	intermediate
agents	["backend-dev","gis"]
created_date	2026-04-27
last_validated
validated_by
status	draft

API Design

Overview

Standards and patterns for designing consistent, well-documented RESTful APIs. Covers naming, HTTP methods, error handling, status codes, and documentation requirements.

Key Concepts

Naming Conventions

• Plural nouns for resources: /users, /orders, /products
• Kebab-case for multi-word: /user-profiles
• Nest related resources: /users/{id}/orders
• Query params for filtering: /users?role=admin&active=true

HTTP Methods

Method	Purpose	Idempotent	Response
GET	Read	Yes	200 + body
POST	Create	No	201 + body + Location
PUT	Replace	Yes	200 + body
PATCH	Partial update	No	200 + body
DELETE	Remove	Yes	204 (no body)

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      {"field": "email", "message": "Invalid email format"}
    ]