Fazendo um paralelo, é quase como perguntar para um vendedor da sua empresa o tempo todo: "Tem venda nova hoje?"
Agora pense na hipótese de que ao invés de você perguntar o tempo todo ao vendedor, quando ele fizer uma nova venda, ele mesmo vai te notificar proativamente.
Funciona exatamente assim uma API event-driven. Ela tem subscribers, ou seja, clients que se inscrevem para serem notificados, e em caso de novos eventos, ela notifica automaticamente todos os clients inscritos.
Existem diferentes abordagens nesse assunto, mas aqui o objetivo é retornar mensagens friendly de erros na sua API, diminuindo a curva de diagnóstico de problemas.
Para isso, você apenas precisa customizar as respostas da sua API com uma estrutura de erros mais organizada e detalhada.
Notem que interessante essa estrutura de response. Além de retornar o status code do HTTP 404, ela te dá um código interno do erro para você navegar na doc, e um link detalhado do erro, com as possíveis soluções.
Se você quer dar possibilidade de testarem rapidamente algo na sua API, então você deve disponibilizar um ambiente para desenvolvimento e testes, mais chamado de sandbox.
Um ambiente sandbox simula basicamente um ambiente de produção. Mas, por não ser o ambiente de produção, o desenvolvedor consegue fazer testes mais avançados, e operações sem receios de errar.
Espero que tenham aprendido bastante com esses conteúdos, e que com isso, consigam me ajudar a colocar o Brasil na lista dos melhores ecossistemas de APIs do mundo =)
Se você foi impactado por essa série, meu único pedido é que compartilhem para todos os developers que vocês conheçam.