1. Key Naming Conventions: `snake_case` vs `camelCase`

Consistency is paramount. Pick a naming convention across your entire API suite and stick to it strictly. `snake_case` (e.g. `user_first_name`) is standard in Python, Ruby, and OAuth specifications, while `camelCase` (e.g. `userFirstName`) is favored in JavaScript/TypeScript environments.

Consistent Key Naming Payload 
// ✅ GOOD: Consistent snake_case keys
{
  "user_id": 9012,
  "first_name": "Marcus",
  "created_at": "2026-07-25T14:30:00Z"
}

// ❌ BAD: Mixed casing conventions
{
  "UserID": 9012,
  "first_name": "Marcus",
  "createdAt": "2026-07-25T14:30:00Z"
}
Explanation: Never mix PascalCase, camelCase, and snake_case in the same API endpoint response.

2. Standardized Error Handling (RFC 7807 Problem Details)

Never return generic `{"error": "Failed"}` strings. Implement RFC 7807 ("Problem Details for HTTP APIs"), which provides a machine-readable JSON structure containing `type`, `title`, `status`, `detail`, and `instance` fields.

RFC 7807 Compliant Error Payload 
{
  "type": "https://api.example.com/errors/invalid-payment",
  "title": "Payment Authorization Failed",
  "status": 402,
  "detail": "Credit card ending in 4242 has expired.",
  "instance": "/v1/orders/ord_9941/pay",
  "invalid_params": [
    {
      "name": "exp_month",
      "reason": "Expiration month must be in the future"
    }
  ]
}
Explanation: RFC 7807 gives client developers explicit, actionable debugging details.

3. Envelope Wrappers & Cursor-Based Pagination

Collection endpoints returning arrays should wrap items inside a root payload key alongside metadata pagination objects (e.g. `next_cursor`, `has_more`, `total_count`).

Paginated Collection Response 
{
  "data": [
    { "id": "usr_1", "name": "Alice" },
    { "id": "usr_2", "name": "Bob" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6Mn0=",
    "has_more": true,
    "page_size": 20
  }
}
Explanation: Cursor-based pagination prevents duplicate item issues during live dataset updates.