Publicar e documentar a API

Todas as APIs devem estar documentadas de forma concisa e atualizada. A forma mais eficaz de documentar o detalhe de uma API é partilhar casos de teste e os dados usados.

No caso de existir necessidade de um grande documento a explicar cada método geralmente indica que a API é muito complexa e sugere-se dividir em componentes mais pequenas de forma a tornar a estrutura da mensagem mais restrita. Na documentação deve garantir que se encontram as informações gerais, o que a API faz, quem pode utilizar, as circunstâncias em que deve ser usada, regras de negócio e dados, como os dados estão disponíveis, cenários de erro, incluindo códigos e mensagens, regras de negócios e dados, em que circunstâncias os dados estão disponíveis/não disponíveis, cenários de sucesso e erro com exemplos, detalhes de parâmetros de pedido e de resposta incluindo dados com valores válidos, tipos de dados, significado e restrições.

Defina o método de autenticação e quaisquer regras de autorização à API. Detalhe a versão e as alterações efetuadas em cada versão, avaliação de compatibilidade com versões anteriores e avaliação de impactos e riscos. Deve incluir a informação segura e os custos de acesso, se aplicável.