> For the complete documentation index, see [llms.txt](https://guias.mosaico.gov.pt/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guias.mosaico.gov.pt/guias-praticos/boas-praticas-para-a-publicacao-de-api-a-consumir-pela-administracao-publica/publicar-e-documentar-a-api.md).

# 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.