Publicar e documentar a API

Todas as API devem estar documentadas de modo conciso e atualizado. 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, por norma indica que a API é muito complexa, e sugere-se dividir em componentes mais pequenas para 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, 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 da API. Detalhe a versão e as alterações feitas em cada versão, a avaliação de compatibilidade com versões anteriores e a avaliação de impactos e riscos. Deve incluir, se aplicável, a informação segura e os custos de acesso.