El problema de las claves de API que nunca caducan
Una clave emitida hace años, que nunca se ha rotado y que hoy sigue siendo válida, no es una comodidad. Es un riesgo que nadie ha revisado de verdad en años.
Argumentos en contra de los formatos de respuesta propietarios
Pregunta por qué una API devuelve un modelo de objetos anidado y personalizado en lugar de una estructura JSON simple y plana, y la respuesta honesta rara vez es técnica. Una estructura propietaria no hace que una consulta sea más rápida ni más precisa. Hace que la respuesta sea más difícil de sustituir, porque cada nombre de campo, cada nivel de anidación y cada código de estado personalizado que tu código aprende a manejar es un pequeño fragmento de conocimiento específico del proveedor incrustado en tu aplicación.
Creemos que eso es al revés. Un formato de respuesta debería describir los datos, no al proveedor. Las coordenadas, las direcciones, los desfases horarios y las elevaciones son los mismos conceptos sin importar quién responda la solicitud, así que la estructura que se devuelve para ellos debería ser casi tan simple como los propios conceptos. Por eso también 17 de nuestros hosts devuelven exactamente la estructura de respuesta de la API de otro proveedor: los datos son nuestros, pero la estructura es una que tu código quizá ya entienda, porque en realidad no nos corresponde inventarla.
Los formatos propietarios también tienden a acumular rarezas que no tienen nada que ver con los datos subyacentes y todo que ver con la historia interna del proveedor. Un campo se renombra por una migración interna y el nombre antiguo se queda como alias obsoleto que nadie quiere eliminar. Un estado se representa como texto en un endpoint y como código numérico en otro porque los crearon equipos distintos con años de diferencia. Nada de esto es malintencionado. Es simplemente lo que ocurre cuando un formato nunca se diseña frente a un estándar externo, sino solo frente al código cambiante de la propia empresa.
La solución no es complicada: elige una estructura simple, documéntala una vez y mantenla estable. Lo hacemos en nuestros propios endpoints nativos y vamos un paso más allá con los hosts compatibles, igualando exactamente la estructura de otro proveedor para que un código que ya interpreta esa estructura no necesite ningún cambio aparte de la URL base y la clave. Es un compromiso mayor de lo que parece. Significa que, cuando la estructura que igualamos tiene un nombre de campo incómodo o una anidación incoherente, mantenemos esa incomodidad, porque todo el valor del host compatible es la fidelidad, no la mejora.
A veces se defiende un formato propietario diciendo que da al proveedor margen para añadir datos más ricos con el tiempo. No creemos que la riqueza exija una estructura desconocida. Los campos opcionales, como la elevación o el detalle de amenazas de IP, pueden ir junto a una respuesta estándar como añadidos y no como sustitutos, de modo que quien no los pide nunca tiene que esquivarlos al interpretar la respuesta, y quien sí los pide los obtiene sin aprender un formato nuevo.
Nada de esto trata realmente del formato JSON como preferencia técnica. Trata de quién asume el coste de una decisión sobre la estructura. Un formato propietario pone ese coste sobre cada cliente que tenga que leer la respuesta. Un formato simple o igualado lo pone sobre nosotros, en el trabajo de diseño de mantener las cosas predecibles. Ahí es donde corresponde ese coste.