O problema das chaves de API que nunca expiram
Uma chave emitida anos atrás, nunca trocada e ainda válida hoje não é uma conveniência. É um risco que ninguém examina de verdade há anos.
Por que a qualidade da documentação importa mais do que a quantidade de recursos
Uma página de preços que lista quarenta endpoints parece mais capaz do que uma que lista quinze. Muitas vezes, ela também é um sinal de alerta. Construir um endpoint é uma fração do trabalho de torná-lo utilizável. O resto é documentação: descrições claras dos parâmetros, exemplos reais de requisições e respostas, observações honestas sobre casos extremos e uma explicação simples do que acontece quando algo dá errado. Pule esse trabalho em quarenta endpoints e você terá quarenta recursos que existem tecnicamente e quase nada na prática.
Preferimos ter menos coisas bem documentadas do que mais coisas mal documentadas. Um desenvolvedor avaliando uma API raramente lê a lista de recursos primeiro. Ele lê a documentação, testa uma requisição de exemplo e forma uma opinião sobre a empresa inteira nos primeiros minutos, com base em se esse exemplo realmente funciona como está escrito. Se não funcionar, a quantidade de recursos na página de marketing deixa de importar, porque a confiança necessária para continuar lendo acabou de ir embora.
Para nós, uma boa documentação significa algumas coisas concretas, não um compromisso vago. Significa que a autenticação é explicada com todos os métodos aceitos mostrados com clareza, e não apenas o que o provedor prefere. Significa que os limites de taxa são informados como números reais, e não como "aplicam-se limites generosos". Significa que os códigos de erro são listados com o que realmente causa cada um, para que um desenvolvedor depurando uma requisição que falhou encontre a resposta na documentação em vez de adivinhar apenas a partir de um código de status. Nada disso exige mais engenharia. Exige alguém decidir que escrever tudo isso com clareza não é uma tarefa burocrática opcional anexada ao produto de verdade.
Uma documentação apenas razoável também tem um custo que se acumula. Um desenvolvedor que não encontra uma resposta na documentação abre um chamado de suporte, e agora resolver essa única dúvida custa tempo da equipe além do tempo de engenharia já gasto construindo o recurso. Multiplique isso por clientes suficientes esbarrando no mesmo parágrafo confuso e a "economia" de escrever uma documentação rasa rapidamente fica negativa. Uma documentação clara não é um extra colocado por cima da API. Ela sai mais barata do que a alternativa, quando você conta a carga de suporte que um parágrafo confuso gera.
Também achamos que a qualidade da documentação é um dos poucos sinais que um possível cliente consegue realmente avaliar antes de se comprometer com uma integração. Não dá para testar facilmente o histórico de disponibilidade de um provedor em cinco minutos, e não dá para julgar totalmente a precisão dos dados sem integrar primeiro. Dá, em cinco minutos, para ler a documentação e julgar se a empresa que a escreveu entendeu o produto bem o bastante para explicá-lo com clareza, ou se a documentação parece algo improvisado e pendurado em uma lista de recursos feita para uma página de vendas.
Uma lista longa de recursos é fácil de escrever. Uma documentação com a qual um desenvolvedor consegue realmente construir na primeira tentativa não é, e essa diferença é exatamente o motivo pelo qual ela importa mais.