Capítulo 5. Documentar a tua API
Este trabalho foi traduzido com recurso a IA. Agradecemos o teu feedback e comentários: translation-feedback@oreilly.com
A documentação é onde os programadores vêm para aprender sobre a tua API. Quer estejas a fornecer um simples ficheiro README ou a desenvolver um site completo para os teus programadores, é fundamental documentar claramente como podem utilizar a tua API da forma mais eficaz.
Brenda Jin, Saurabh Sahni e Amir Shevat, Designing Web APIs (O'Reilly, 2018)
No Capítulo 4, criaste a tua primeira API para cumprir as histórias de utilizador identificadas no Capítulo 1. Os principais utilizadores para quem as desenvolveste são utilizadores de ciência de dados e fornecedores de sites de aconselhamento. A API permitirá que eles criem produtos analíticos, como painéis, gráficos e modelos, usando os dados de fantasia do SportsWorldCentral (SWC). Agora vais criar documentação para os ajudar a utilizar a tua API. A documentação e as funcionalidades como os kits de desenvolvimento de software (SDKs) melhoram a experiência do programador (DX) para os teus utilizadores técnicos.
Enviar um sinal de confiança
Um trabalho importante da tua API docs é sinalizar confiança aos potenciais consumidores da API. Se não confiarem em ti, não utilizarão a tua API. Se os consumidores da API vão chamar a tua API várias vezes, vão construir uma integração, que é basicamente um código que chama o teu código repetidamente. No caso da API do SWC, pode ser um site ...