camelCase vs snake_case Isn't a Style Choice in APIs — It's a Contract, and Changing It Breaks Your Consumers

The naming convention you choose for a variable at 2 AM will be read by your future self, your colleagues, and potentially automated tools for years — and the case style isn't an aesthetic preference but a contractual signal about the kind of identifier it is, what it belongs to, and how it's expected to be used

The previous articles on this site covered naming conventions (camelCase, snake_case, kebab-case), Unicode case conversion challenges, title case style guides, case sensitivity in login systems, and why different layers of the stack use different case conventions. This article addresses case conventions in modern software development contexts beyond naming — specifically how case style affects API contract design, code generation tools, and the interoperability between systems that have different native conventions.

Case as a contract in API design

When an API returns JSON, the case style of its field names is an implicit contract:

{
  "userId": 12345,
  "firstName": "Jane",
  "lastLoginAt": "2024-11-15T09:30:00Z"
}

camelCase is the de facto standard for JSON APIs — it matches JavaScript's native object property convention, meaning JavaScript consumers can access response.userId without transformation. This convention is documented in Google's JSON Style Guide and followed by the majority of REST APIs.

Switching cases mid-API breaks consumers. If v1 returned user_id (snake_case) and v2 returns userId (camelCase) without a versioning strategy, every client must update. This is a breaking change even if the field semantics are identical.

GraphQL's convention: field names in GraphQL schemas use camelCase for field names and PascalCase (UpperCamelCase) for type names. This is a community convention enforced by most GraphQL tooling.

Code generation and case transformation

OpenAPI/Swagger code generators produce client libraries in the target language's native case convention — regardless of what the API uses internally. A Python SDK generated from a camelCase API will expose user_id (snake_case) to Python code; a TypeScript SDK from the same API will expose userId. The SDK layer translates between conventions.

The case mismatch problem in code generation:

When a database uses snake_case column names (standard in PostgreSQL), an ORM maps them to the application layer with optional case transformation. In Django (Python), the ORM exposes snake_case fields matching the database. In Sequelize (Node.js), the ORM can optionally transform to camelCase for JavaScript consumers. In Hibernate (Java), field names in camelCase map to snake_case by naming convention.

If case transformation is not configured consistently, you end up with inconsistent field names across your stack — user_id in the database, userId in the API response, user_id in Python backend code, userId in the TypeScript frontend. Each layer's convention is internally consistent, but the system has no single source of truth about what the field is called.

SCREAMING_SNAKE_CASE and constants: the semantic encoding

SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT, API_BASE_URL, DEFAULT_TIMEOUT_MS) is not just a style preference — in most languages it semantically signals:

• The value is a compile-time or module-level constant
• It should not be reassigned during program execution
• It is global in scope (or module-scope) rather than local

The convention is enforced by linters (ESLint, Pylint, Checkstyle) — flagging max_retry_count = 3 as a style violation when it should be MAX_RETRY_COUNT = 3. This means the case style carries type-level semantic information about mutability and scope.

Environment variables follow the same convention (DATABASE_URL, API_KEY, NODE_ENV) because they're runtime constants injected from outside the program — the SCREAMING_SNAKE_CASE signals "this is a value that doesn't change during execution."

Kebab-case's specific domain: URLs, CSS, and HTML attributes

Kebab-case (my-component, user-profile, background-color) is dominant in exactly three contexts and rare elsewhere:

CSS property names (background-color, font-family, margin-top): all CSS property names use kebab-case. The hyphen was chosen because CSS identifiers allow hyphens and the case-insensitive CSS specification naturally accommodated readable hyphenated names.

HTML attribute names (data-user-id, aria-labelledby, x-csrf-token): kebab-case in HTML attributes, particularly custom data-* attributes and ARIA attributes.

URL slugs and paths (/blog/my-article-title, /api/user-profile): hyphens in URLs are preferred over underscores for SEO purposes (Google treats hyphens as word separators; underscores are treated as word-joining characters, meaning my_article is indexed as the single word "myarticle").

Why kebab-case is rare in programming languages: the hyphen - is the subtraction operator in most languages — my-variable is parsed as my minus variable in most programming contexts, making kebab-case invalid for variable names. HTML and CSS are not general-purpose programming languages and don't have this operator conflict.

The database-to-API case transformation pattern

A pragmatic pattern for systems spanning multiple case conventions:

1. Database layer: snake_case column names (PostgreSQL convention, SQL Standard)
2. ORM/Query layer: transparent mapping, snake_case Python/snake_case Ruby (staying native)
3. API serialization layer: explicit camelCase transformation in the serializer/DTO
4. API contract: camelCase JSON, documented in OpenAPI spec
5. Frontend consumer: camelCase JavaScript/TypeScript (matches JSON directly)

The key principle: transformation happens at exactly one boundary (the serialization layer at the API edge), not scattered throughout the codebase. Every layer uses its native convention; only the boundary layer translates.

What breaks this pattern: bypassing the serialization layer (directly returning database query results as API responses), inconsistent transformation (some endpoints transform, others don't), or changing the convention at one layer without updating others.

How to use the Case Converter on sadiqbd.com

1. For API field name normalisation: paste JSON field names or database column names and convert to the target API convention (camelCase for JSON, snake_case for Python backend, SCREAMING_SNAKE for constants)
2. For slug generation: convert article titles or product names to kebab-case for use as URL slugs — the tool handles spaces, special characters, and uppercase correctly
3. For code migration: when changing naming conventions during a refactor, convert existing identifiers in bulk before search-and-replacing in the codebase

Frequently Asked Questions

Why do some programming languages use different conventions even within the standard library? Historical accumulation and committee decisions. Python's standard library, for example, has os.path.join (snake_case) but older modules like ConfigParser (PascalCase) and urllib.parse alongside the older urllib2 (now removed) — inconsistencies that accumulated across Python 2.x development before PEP 8 fully standardised conventions. Java's standard library uses camelCase for methods but ALL_CAPS for constants, with class names in PascalCase — internally consistent, but different from Python's conventions. Most language communities have published style guides that post-date the standard library's earliest code; what's inside the standard library reflects the conventions at the time those modules were written.

Is the Case Converter free? Yes — completely free, no sign-up required.

Try the Case Converter free at sadiqbd.com — convert text between camelCase, snake_case, kebab-case, PascalCase, and more.