JSON se ha convertido en el lenguaje universal de las APIs web. Prácticamente todas las APIs REST, webhooks y archivos de configuración lo utilizan. Sin embargo, a pesar de su aparente simplicidad — son solo pares clave-valor y arreglos — un JSON mal estructurado crea problemas reales: los clientes de API se rompen con nulos inesperados, el análisis de fechas falla entre zonas horarias y las convenciones de nomenclatura inconsistentes hacen que los cambios en toda la base de código sean dolorosos.
Convenciones de Nomenclatura: Elige Una y Aplícala
Las dos convenciones dominantes son camelCase (nombreCompleto, creadoEn) y snake_case (nombre_completo, creado_en). camelCase es la convención de JavaScript y se siente natural al consumir APIs en JS/TS. snake_case es preferido en los ecosistemas de Python y Ruby. No hay una elección universalmente "correcta" — pero la consistencia es obligatoria.
Mezclar convenciones dentro de la misma API es el peor resultado. Una API que devuelve userId en un endpoint y user_id en otro obliga a cada cliente a normalizar los datos antes de usarlos, duplicando la superficie de error. Si estás construyendo una nueva API, elige una convención y documéntala.
Los campos booleanos deben leerse como afirmaciones verdaderas: es_activo, tiene_permiso, puede_editar. Evita es_no_eliminado o no_tiene_errores — los booleanos negativos son cognitivamente más difíciles de analizar y hacen que los condicionales sean propensos a errores.
Nulo, Ausente y Vacío: No Son lo Mismo
null significa que el campo existe pero no tiene valor. Un campo ausente significa que el campo no es aplicable en este contexto. Una cadena vacía "" o un arreglo vacío [] significa que el campo existe y está explícitamente vacío. Estas distinciones importan para los consumidores de la API: una biografía null significa "aún no se ha establecido biografía", mientras que un campo biografía ausente podría significar "este endpoint no devuelve biografías".
Para arreglos, devuelve [] en lugar de null cuando no hay elementos. Un arreglo vacío es una colección válida que los clientes pueden iterar de forma segura — un null requiere una verificación de nulo antes de cada bucle.
Evita usar null como valor centinela para "desconocido", "N/A" o "cargando". null debería significar solo una cosa: se sabe que el valor está ausente. Sobrecargar null con múltiples significados obliga a los clientes de la API a inferir el contexto de los campos circundantes.
Fechas y Timestamps: Siempre Usa ISO 8601
El formato de fecha es la fuente más común de errores de análisis de API. Usa siempre el formato ISO 8601: 2025-06-07T14:30:00Z. Este formato es inequívoco, analizable por la biblioteca estándar de cualquier lenguaje de programación moderno, ordenable como cadena e incluye información de zona horaria.
Siempre incluye información de zona horaria. Almacenar y transmitir fechas en UTC (el sufijo Z o +00:00) elimina la aritmética de zona horaria en el servidor y hace que la conversión a hora local sea responsabilidad del cliente.
Para timestamps Unix, usa segundos (no milisegundos) por convención para APIs del lado del servidor. El Date.now() de JavaScript devuelve milisegundos, pero las convenciones de timestamp Unix y la mayoría de las bases de datos usan segundos. Documenta tu elección explícitamente.
Errores Estructurales Que Causan Problemas
Los objetos profundamente anidados son difíciles de consultar y cambiar. Un objeto con seis niveles de anidamiento es difícil de navegar para los consumidores y hace que las actualizaciones parciales sean dolorosas. Aplana donde sea posible.
Devolver formas diferentes desde el mismo endpoint según la entrada es un antipatrón. Si GET /usuarios devuelve { nombre } para algunos usuarios y { nombre, apellido } para otros según la fecha de creación, cada consumidor debe manejar ambas formas. Las formas de respuesta estables y consistentes hacen que el almacenamiento en caché, el registro y el código del cliente sean dramáticamente más simples.
Incluir campos calculados junto con los datos sin procesar agrega valor. Si almacenas un timestamp Unix, también devuelve la cadena formateada ISO 8601. Si almacenas un precio en centavos, también devuelve la cadena de moneda formateada. Esto reduce el cómputo del lado del cliente.
El buen diseño de APIs JSON tiene menos que ver con la brillantez y más con la consistencia y la previsibilidad. Una API que siempre devuelve la misma forma, usa una convención de nomenclatura, maneja null intencionalmente y formatea las fechas de forma inequívoca se vuelve invisible — los desarrolladores pueden enfocarse en construir funciones en lugar de código defensivo de análisis.