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.
Por qué la calidad de la documentación importa más que el número de funciones
Una página de precios que enumera cuarenta endpoints parece más capaz que una que enumera quince. También es, con frecuencia, una señal de alarma. Crear un endpoint es una fracción del trabajo de hacerlo utilizable. El resto es documentación: descripciones claras de los parámetros, ejemplos reales de solicitudes y respuestas, notas honestas sobre los casos límite y una explicación sencilla de lo que pasa cuando algo sale mal. Sáltate ese trabajo en cuarenta endpoints y obtendrás cuarenta funciones que existen técnicamente y apenas existen en la práctica.
Preferimos tener menos cosas bien documentadas que más cosas mal documentadas. Un desarrollador que evalúa una API rara vez lee primero la lista de funciones. Lee la documentación, prueba una solicitud de ejemplo y se forma una opinión sobre toda la empresa en los primeros minutos según si ese ejemplo funciona tal como está escrito. Si no funciona, el número de funciones en la página comercial deja de importar, porque la confianza necesaria para seguir leyendo acaba de irse.
Para nosotros, una buena documentación significa unas cuantas cosas concretas, no un compromiso vago. Significa que la autenticación se explica mostrando con claridad todos los métodos aceptados, no solo el que prefiere el proveedor. Significa que los límites de frecuencia se indican con números reales, no con "se aplican límites generosos". Significa que los códigos de error se enumeran con lo que realmente provoca cada uno, para que un desarrollador que depura una solicitud fallida encuentre la respuesta en la documentación en lugar de adivinarla solo a partir de un código de estado. Nada de esto requiere más ingeniería. Requiere que alguien decida que escribirlo con claridad no es una tarea opcional añadida al producto real.
La documentación que solo es aceptable también tiene un coste acumulativo. Un desarrollador que no encuentra una respuesta en la documentación abre un ticket de soporte, y ahora resolver esa única pregunta cuesta tiempo del personal además del tiempo de ingeniería ya invertido en crear la función. Multiplica eso por suficientes clientes que tropiezan con el mismo párrafo poco claro y el "ahorro" de escribir documentación escasa se vuelve negativo rápidamente. Una documentación clara no es un extra agradable colocado encima de la API. Es más barata que la alternativa, una vez que cuentas la carga de soporte que genera un párrafo poco claro.
También creemos que la calidad de la documentación es una de las pocas señales que un posible cliente puede evaluar de verdad antes de comprometerse con una integración. No puedes comprobar fácilmente el historial de disponibilidad de un proveedor en cinco minutos, y no puedes juzgar del todo la precisión de los datos sin integrarte primero. Sí puedes, en cinco minutos, leer la documentación y juzgar si la empresa que la escribió entendía el producto lo bastante bien como para explicarlo con sencillez, o si la documentación parece un añadido de última hora pegado a una lista de funciones pensada para una página comercial.
Una lista larga de funciones es fácil de escribir. Una documentación con la que un desarrollador puede construir a la primera no lo es, y esa diferencia es exactamente la razón por la que importa más.