The near-universal convention for REST API URL paths is kebab-case: all lowercase, words separated by hyphens.

• ▸GET /user-profiles
• ▸GET /blog-posts/{post-id}
• ▸POST /password-reset-requests
• ▸GET /order-line-items

Google's API design guide, Microsoft's REST API guidelines, and Stripe, GitHub, and Twilio all use kebab-case for URL paths. The reasons are practical: URLs are case-sensitive on Linux servers, so uppercase in a path creates inconsistency risks. Hyphens are the web standard for word separation in URLs — Google treats hyphens as word separators for indexing, and URL parsers handle hyphens cleanly without encoding.

snake_case (/user_profiles) was common in older APIs (Twitter's v1 API used it) but has fallen out of favor. camelCase (/userProfiles) creates case-sensitivity risks and reads poorly in URLs. kebab-case has become the standard for new API design.

Query parameters do not have a single dominant convention — different ecosystems favor different formats. The two most common are snake_case and camelCase.

snake_case query parameters:

• ▸GET /users?sort_by=created_at&page_size=20
• ▸GET /products?min_price=10&max_price=100

camelCase query parameters:

• ▸GET /users?sortBy=createdAt&pageSize=20
• ▸GET /products?minPrice=10&maxPrice=100

Python and Ruby APIs (Django REST Framework, Rails) typically use snake_case for query parameters, consistent with their language conventions. JavaScript-heavy APIs often use camelCase. Google APIs tend to use camelCase. The most important rule is internal consistency: pick one format and apply it to every query parameter across your entire API surface.

Avoid kebab-case for query parameter names. While hyphens are valid in query strings, they are invalid as variable names in most languages — meaning every consumer of your API will need to rename the parameter before using it in code. snake_case and camelCase both map directly to valid identifiers.

JSON key casing is one of the most debated API design decisions, and it reflects a real tension: the two most common backend languages have conflicting conventions.

camelCase JSON keys are the default expectation in JavaScript ecosystems. Since JSON was designed for JavaScript, and JavaScript uses camelCase for object properties, camelCase keys feel native to frontend developers and Node.js backends:

• ▸{ "userId": 123, "firstName": "Alex", "createdAt": "2026-01-01" }
• ▸Used by: GitHub API, Stripe API, Salesforce API, most Node.js APIs

snake_case JSON keys are the convention in Python and Ruby backends. Django REST Framework, FastAPI, and Rails APIs default to snake_case because it matches the language's variable naming:

• ▸{ "user_id": 123, "first_name": "Alex", "created_at": "2026-01-01" }
• ▸Used by: Twitter API v2, Reddit API, many Python-backed APIs

The practical guidance: use camelCase if your API is consumed primarily by JavaScript frontends and you want zero friction for frontend developers. Use snake_case if your backend is Python or Ruby and your API consumers are also backend developers or expect Python-style data. Whichever you choose, be consistent — mixing camelCase and snake_case keys within the same API response is worse than either choice alone.

HTTP headers use a format called Train-Case (also called HTTP-Header-Case): each word is capitalized and words are separated by hyphens.

• ▸Content-Type
• ▸Authorization
• ▸Accept-Language
• ▸X-Request-Id
• ▸Cache-Control
• ▸X-Api-Key

This is defined by the HTTP specification itself for standard headers, and the convention is followed for custom headers. HTTP/1.1 headers are technically case-insensitive — a server must accept 'content-type' and 'CONTENT-TYPE' as equivalent to 'Content-Type' — but Train-Case is the canonical form used in all documentation, examples, and tooling.

Custom headers for your API should use the same Train-Case format with an X- prefix if they are non-standard: X-Request-Id, X-Rate-Limit-Remaining, X-Correlation-Id. Note that the X- prefix convention is technically deprecated by RFC 6648, but it remains widely used for clarity.

A well-designed API applies its casing choices consistently at every layer. Here is what a consistent API looks like using camelCase for JSON bodies:

• ▸URL path: POST /user-profiles (kebab-case)
• ▸Query parameter: GET /user-profiles?sortBy=createdAt (camelCase)
• ▸Request header: Content-Type: application/json (Train-Case)
• ▸Request body key: { "firstName": "Alex", "emailAddress": "alex@example.com" } (camelCase)
• ▸Response body key: { "userId": 456, "createdAt": "2026-08-11" } (camelCase)

The same pattern using snake_case for JSON bodies would keep kebab-case paths and Train-Case headers, but swap query parameters and body keys to snake_case.

One useful approach for APIs serving both JavaScript and Python consumers: use camelCase in the API contract, and let each language's serialization layer handle the conversion. Python's requests library and most JSON serializers can be configured to translate snake_case Python variables to camelCase JSON keys automatically.