camelCase vs snake_case: ¿Qué formato usar en nombres de campos JSON?

En el diseño arquitectónico de sistemas distribuidos, las APIs no son solo conductos para la interacción del sistema; son contratos que conectan diferentes pilas tecnológicas, culturas organizativas e incluso eras de desarrollo. Dentro de los detalles de diseño de las APIs RESTful, un tema aparentemente menor provoca un debate interminable: ¿Los nombres de los campos JSON deben usar camelCase o snake_case?

Esto no es meramente una elección estética. Toca el "desajuste de impedancia" entre las capas de persistencia del backend y las capas de presentación del frontend, involucrando el rendimiento de la serialización, la eficiencia de la transmisión de red, la Experiencia del Desarrollador (DX) y la psicología cognitiva.

Basado en la historia de los lenguajes de programación, los mecanismos de implementación técnica subyacentes y las decisiones arquitectónicas de gigantes de la industria como Google y Stripe, este artículo proporciona una guía de decisión de nivel experto.

1. Orígenes Históricos: Una Elección Semiótica

Para entender este debate, debemos rastrear la evolución de los lenguajes informáticos. Las convenciones de nombres no aparecieron de la nada; son productos de las limitaciones de hardware y las culturas comunitarias de épocas específicas.

El Origen de snake_case: C y la Filosofía Unix

La popularidad de snake_case (por ejemplo, user_id) se remonta a C y Unix en la década de 1970. Aunque los teclados primitivos (como el Teletype Model 33) tenían teclas de mayúsculas, muchos compiladores antiguos no distinguían entre mayúsculas y minúsculas. Para distinguir claramente las palabras en pantallas de baja resolución, los programadores introdujeron el guion bajo para simular espacios en el lenguaje natural. Este hábito se arraigó profundamente en los estándares de las bases de datos SQL. Hasta el día de hoy, el estilo predeterminado de nombres de columna para PostgreSQL y MySQL sigue siendo snake_case, sentando las bases para la futura fricción de mapeo entre APIs y bases de datos.

El Auge de camelCase: La Hegemonía de Java y JavaScript

camelCase (por ejemplo, userId) surgió con la Programación Orientada a Objetos (Smalltalk, C++, Java). Java estableció el estándar industrial de "PascalCase para clases, camelCase para métodos/variables". El punto de inflexión decisivo fue el nacimiento de JavaScript. Aunque JSON se originó a partir de literales de objetos JS, la biblioteca estándar de JS (por ejemplo, getElementById) adoptó camelCase de forma generalizada. A medida que AJAX y JSON reemplazaron a XML como los formatos dominantes de intercambio de datos, camelCase ganó un estatus "nativo" en el dominio web.

2. Conflicto Central: Desajuste de Impedancia de las Pilas Tecnológicas

Cuando los datos fluyen entre diferentes lenguajes, inevitablemente encuentran un "desajuste de impedancia".

La Perspectiva del Backend (Python/Ruby/SQL)

En el backend, las comunidades de Python (PEP 8) y Ruby recomiendan encarecidamente snake_case.

• Python/Django/FastAPI: Tus modelos Pydantic suelen corresponder directamente a las estructuras de tablas de la base de datos:

class UserProfile(BaseModel):
    first_name: str  # Convención de Python
    last_name: str

Si la API exige camelCase, debes configurar alias o convertidores en la capa de serialización. Si bien es factible, esto añade una capa de lógica de mapeo.

• Bases de Datos SQL: La mayoría de los nombres de columna de las bases de datos usan snake_case. Si la API usa camelCase, la capa ORM debe manejar consistentemente la conversión.
• La Elección de Stripe: La razón por la que Stripe y GitHub eligieron firmemente snake_case se debe en gran parte a que sus arquitecturas iniciales se construyeron sobre la pila de Ruby. Exponer los modelos internos directamente aseguró la consistencia del backend.

La Perspectiva del Frontend (JavaScript/TypeScript)

En el navegador, camelCase es el rey absoluto.

• Fragmentación del Estilo de Código: Si una API devuelve snake_case, el código frontend se vuelve inconsistente:

const user = await fetchUser();
console.log(user.first_name); // Viola la regla de camelcase de ESLint
render(user.email_address);

ESLint marcará esto como una advertencia, obligando a los desarrolladores a deshabilitar la regla o a convertir los datos inmediatamente después de recibirlos.

• Dolor al Desestructurar: En el desarrollo moderno de JS/TS, la desestructuración de objetos es omnipresente. Si los campos son snake_case, deben ser renombrados durante la desestructuración para evitar contaminar el ámbito local:

// Renombrado verboso
const { first_name: firstName, last_name: lastName } = response.data;

Esto aumenta el código repetitivo y la probabilidad de errores.

3. Mitos de Rendimiento: Serialización y Transmisión de Red

Respecto al rendimiento, existen dos mitos comunes: "La conversión de nombres de campo es demasiado lenta" y "Los guiones bajos aumentan el tamaño de la carga útil." Aclaremos con datos.

Mito 1: Sobrecarga de Conversión en Tiempo de Ejecución

• Lenguajes Dinámicos: En Python o Ruby, convertir nombres de campo mediante reemplazo de expresiones regulares en cada solicitud consume CPU. Sin embargo, los frameworks modernos (como Pydantic v2, reescrito en Rust) minimizan esta sobrecarga mediante mapeos de esquemas precalculados.
• Lenguajes Estáticos (Go/Java/Rust): Esto es efectivamente "costo cero". Las etiquetas de struct de Go (json:"firstName") o las cachés de mapeo de Java Jackson se determinan en tiempo de compilación o inicio. La ejecución en tiempo de ejecución implica una simple copia de bytes, no un cálculo dinámico.

Nota: Nunca realices una conversión recursiva global en el frontend (hilo principal del navegador) utilizando interceptores (por ejemplo, Axios). Para respuestas grandes, esto causa intermitencia de la página y agotamiento de la memoria. Conclusión: El backend debe encargarse de la conversión.

Mito 2: Tamaño de Transmisión y Compresión

Teóricamente, first_name es un byte más largo que firstName. Sin embargo, con la compresión Gzip o Brotli habilitada (configuración HTTP estándar), esta diferencia prácticamente desaparece.

• Principio: Los algoritmos de compresión se basan en la "referenciación de cadenas duplicadas". En un array JSON, las claves son altamente repetitivas. El algoritmo almacena first_name en un diccionario al primer encuentro y reemplaza las ocurrencias posteriores con un pequeño puntero.
• Benchmarks: Las pruebas demuestran que bajo Gzip nivel 6, la diferencia de tamaño entre ambos estilos suele ser entre 0.5% y 1%. A menos que estés transmitiendo datos a través de enlaces satelitales, esto no es un problema.

4. Experiencia del Desarrollador (DX) y Psicología Cognitiva

La arquitectura no se trata solo de máquinas; se trata de personas.

• Legibilidad de snake_case: La psicología cognitiva sugiere que los guiones bajos proporcionan una separación visual clara. parse_db_xml es procesado por el cerebro más rápidamente que parseDbXml, especialmente cuando se trata de acrónimos consecutivos (por ejemplo, XMLHTTPRequest vs XmlHttpRequest). Esta es una de las razones por las que la documentación de Stripe se considera altamente legible.
• Consistencia de camelCase: El estado de flujo que aporta la consistencia de pila completa es más crítico. Para los equipos de JS/TS de pila completa, usar camelCase tanto en el frontend como en el backend permite la reutilización directa de definiciones de tipo (Interface/Zod Schema), eliminando completamente la carga cognitiva de la "traducción mental".

5. Estándares de la Industria y Justificación

6. Consejo Arquitectónico Profundo: Desacoplamiento y DTOs

Un antipatrón común es el "Paso directo": serializar directamente las entidades de la base de datos para devolverlas.

• Si haces esto, y tus columnas de DB son snake_case, tu API se convierte en snake_case.
• Riesgo: Esto viola el principio de ocultamiento de información, expone las estructuras de las tablas y crea un fuerte acoplamiento entre la API y la DB. Si se renombra la DB, la API se rompe.

Mejor Práctica: Introduce una capa de DTO (Objeto de Transferencia de Datos). Independientemente de cómo se nombre la base de datos subyacente, debes definir un contrato de API independiente (DTO). Dado que estás definiendo un DTO, ¿por qué no definirlo como camelCase para adherirte a los estándares web? Las herramientas de mapeo modernas (MapStruct, AutoMapper, Pydantic) manejan esta conversión sin esfuerzo.

7. Mirando Hacia el Futuro: GraphQL y gRPC

GraphQL: La comunidad adopta casi al 100% camelCase. Si tu equipo planea introducir GraphQL en el futuro, diseñar APIs REST con camelCase ahora es una estrategia inteligente de "compatibilidad futura".

gRPC: El estándar Protobuf dicta: los archivos .proto usan snake_case para las definiciones de campo, pero deben convertirse a camelCase cuando se mapean a JSON. Esta es la solución estándar de Google para entornos multilingües.

8. Resumen y Matriz de Decisión

No hay un bien o un mal absoluto, solo compensaciones. Aquí está el marco de decisión final:

Recomendado: Por Defecto a camelCase

Para la gran mayoría de las APIs RESTful nuevas y de propósito general que se enfrentan a clientes web/aplicaciones, se recomienda encarecidamente camelCase.

Razón: Alinear con el dominio de JSON/JavaScript/TypeScript, adoptando los hábitos del 90% de los consumidores.

Herramientas: Obtén el mejor soporte de los generadores de código OpenAPI, Swagger UI y los IDE modernos.

¿Cuándo usar snake_case?

1. Consumidores Específicos: Los usuarios principales de la API son científicos de datos de Python o operadores de sistemas (Curl/Bash).

2. Sistemas Heredados: Las APIs existentes ya son snake_case. Consistencia > Mejor Práctica. No mezcles estilos dentro del mismo sistema.

3. Extremismo en la Velocidad del Backend: Usando Python/Ruby sin los recursos para mantener una capa DTO, pasando directamente los modelos de la base de datos.

Tabla de Decisiones

La esencia del diseño de APIs es la empatía. En el contexto de las APIs web, encapsular la complejidad en el backend (manejando el mapeo) y dejar la conveniencia al usuario (adhiriéndose a los hábitos de JS) es la elección que refleja mayor profesionalismo.