REST API Conventions

REST API Conventions — RESTful API Design Conventions Reference

A reference of naming rules, status codes, and pagination patterns used by the api-architect agent when designing REST APIs.

Target Agent

api-architect — Directly applies the conventions in this skill to API designs.

URL Naming Rules

Basic Principles

Resource URL Patterns

Relationship Resources

GET  /users/{userId}/orders           -- User's order list
GET  /users/{userId}/orders/{orderId} -- User's specific order
POST /users/{userId}/orders           -- Create order for user

Non-CRUD Actions (RPC-Style Permitted)

POST /orders/{id}/cancel        -- Cancel order
POST /users/{id}/verify-email   -- Verify email
POST /reports/generate          -- Generate report
POST /cart/checkout             -- Proceed to checkout

HTTP Status Code Selection Guide

Success (2xx)

Client Errors (4xx)

Server Errors (5xx)

Pagination Patterns

Offset-Based (Traditional)

GET /products?page=2&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

• Pros: Simple implementation, random page access
• Cons: Performance degradation with large datasets (OFFSET)

Cursor-Based (Recommended)

GET /products?cursor=eyJpZCI6MTIzfQ&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "eyJpZCI6MTQzfQ",
    "hasMore": true
  }
}

• Pros: Excellent performance with large datasets, safe for real-time data
• Cons: No total count or random page access

Selection Criteria

Filtering/Sorting/Search Patterns

Filtering

GET /products?category=electronics&price_min=10000&price_max=50000&status=active

Sorting

GET /products?sort=price&order=asc
GET /products?sort=-created_at,+name    (prefix style: - descending, + ascending)

Search

GET /products?q=keyboard                (full-text search)
GET /products?name=keyboard             (specific field)

Field Selection (Sparse Fieldsets)

GET /products?fields=id,name,price      (only needed fields)

Error Response Standard Format

RFC 7807 (Problem Details)

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request data is invalid",
  "instance": "/products",
  "errors": [
    {
      "field": "price",
      "code": "INVALID_RANGE",
      "message": "Price must be greater than 0"
    }
  ]
}

Versioning Strategies

Recommended: URL Path (/v1/) — Most intuitive and widely adopted

Version Deprecation Policy

• New version released -> Maintain old version for 12 months
• Deprecation headers: Deprecation: true, Sunset: 2025-12-31
• Provide migration guide

Response Envelope Pattern

Single Resource Response

{
  "data": { "id": 1, "name": "Product" },
  "meta": { "requestId": "abc-123" }
}

List Response

{
  "data": [{ "id": 1 }, { "id": 2 }],
  "pagination": { "page": 1, "limit": 20, "total": 150 },
  "meta": { "requestId": "abc-123" }
}

Idempotency