Se você desenvolve uma API, especialmente uma API REST, deve garantir que ela seja bem documentada. Não existe uma maneira aceita exclusivamente de formalizar serviços RESTful. Mesmo assim, você deseja atrair desenvolvedores terceirizados e tornar o uso da API o mais fácil possível.
O Quickstart
Nada é tão bom para começar rápido com o uso de uma API. Para este propósito, o site de documentação deve fornecer alguns passos simples para começar.
A descrição detalhada
Os itens a seguir são obrigatórios para cada documentação de API:
- Método HTTP e URL , por exemplo, GET / crises
- Formatos suportados , por exemplo, JSON, JSONP, RDF
- Parâmetros suportados . Descreva claramente quais parâmetros são obrigatórios e quais são opcionais e qual é a semântica por trás desses parâmetros.
- Chamada de exemplo : como é uma chamada concreta com parâmetros e o cabeçalho HTTP de resposta, por exemplo, pelo uso de curl
- Saída : os dados que são retornados. Possível como instância concreta, por exemplo, saída de exemplo JSON ou como diagrama de classe UML.
- Link para mais ajuda : você pode, por exemplo, vincular a criação de uma nova pergunta em StackOverflow.com
Recursos adicionais
O código
É realmente útil para o desenvolvedor olhar para o código de exemplo . Você pode usar para isso, por exemplo, gitorious.org, github.com, bitbucket.org ou qualquer outro serviço de hospedagem que facilite a bifurcação.
O Cliente Exemplo
Além do código-fonte, também é útil ter uma instância desse código em execução. Isso simplifica o entendimento e permite ao desenvolvedor testar o cliente sem a necessidade de configurá-lo. Isso só é possível se o cliente for um aplicativo da web.
Anotação
Eu vim com esta diretriz durante o desenvolvimento da API REST Sigimera (consulte http://api.sigimera.org ). A API não está finalizada, nem esta diretriz, mas deve ajudar a lembrar os pontos essenciais para a documentação.
Por favor, me avise se eu esqueci algo.