devigorgarcia / htttinder-api

httTinder-Api

1. Uma boa descrição

As pessoas precisam saber em poucas palavras sobre o que se trata e para qual finalidade é direcionada sua API. 2. Padronização de nomenclaturas

A padronização de nomenclaturas facilitará a navegação e absorção do conteúdo da sua documentação 3. Boa divisão das funcionalidades

Dividir muito bem as informações é essêncial, para que assim o consumo da documentação seja facil.

Criar seções e subceções ajuda o usuário a não se perder e também a encontrar com maior facilidade o que procura. 4. Abrangir 100% das possibilidades

Não adianta ter uma documentação bem escrita, com uma boa divisão, se ela não abrangir 100% das possibilidades de sucessos e erros da sua api. 5. Ser claro e direto

Não faça textos longos e maçantes. Sabemos muito bem o quanto nosso tempo é precioso, consumir a documentação é extretamente importante, porém isso deve ser um suporte e não um impedimento. 6. Documentar erros é muito importante

Nunca esqueça, Erros são tão importantes quantos sucessos!

Jamais deixe de criar boas mensagens de erro para sua API. E ainda mais, não esqueça de documentar tudo! 7. Padronizar status e mensagens/corpo dos retornos

Escolha um padrão para os retornos das suas rotas. Tanto de sucessos quanto de erros.

Podemos por exemplo escolher que nossa api sempre retornará um objeto com a propriedade data. A qual conterá os dados do retorno. Por exemplo: