Como um provedor de API, é importante considerar como os consumidores interagem com sua API. Enquanto a maioria das pessoas deixam essa tarefa para o final, o design de API deveria na verdade começar com uma documentação clara e concisa. Essa prática é chamada com frequência de Documentation Driven Design ou Documentation Driven Development e é seguida por muitas pessoas ao redor do mundo. Dentre os benefícios dessa abordagem, está:
- O projeto é melhor executado conforme você tem tempo de pensar cada aspecto antes da implementação
- É muito mais fácil escrever documentação logo no começo do projeto quando sua mente está fresca e suas ideias ficam mais fáceis de serem colocadas no papel
- Quando você (ou sua equipe) começam a implementar API, há uma especificação clara a seguir
- Discutir ideias e possíveis mudanças são bem mais fáceis quando já existe uma documentação escrita
Abaixo você confere itens essenciais para uma boa documentação de API:
Itens fundamentais de documentação de APIs
Esses são os itens que toda documentação de API deve oferecer. Sem eles, consumidores terão uma série de dificuldades para compreender como suas APIs podem ser usadas e não será raro eles simplesmente desistirem.
- Autenticação: Informações descrevendo qual método de autenticação sua API usa é fundamental. Se você usa OAuth, não se esqueça de explicar como configurar uma aplicação OAuth para obter a API Key e Secret.
- Erros: Deve ser especificado como os erros são comunicados aos consumidores da API. É interessante você explicar se segue algum padrão de erro, como HTTP Status Codes, por exemplo, e como os erros são geralmente transmitidos dentro das responses.
- Endpoints: É importante colocar informações sobre como consumir endpoints, incluindo requests e responses. Isso é considerado a principal sessão na qual você expõe todos os métodos da sua API, explica como podem ser obtidas e observar quais parâmetros são permitidos.
Com esses três tópicos, você está começando muito bem, já que está documentando boa parte do que é necessário para consumir sua API. Mas isso costuma não ser suficiente. Conforme você obtém consumidores mais sofisticados, você acabará precisando oferecer uma documentação de aspectos não funcionais da sua API.
Itens experts de documentação de APIs
Incorporar os pontos seguintes fará sua API se destacar diante da concorrência. Embora seja verdade que alguns consumidores possam negligenciar essas sessões em específico, aqueles orientados a negócios podem considera-las fundamentais e decisivas.
- Termo de uso: É muito importante incluir as condições de uso da sua API. Permissões e restrições precisam ser declaradas de forma clara para que consumidores compreendam quais práticas de uso da API são permitidas.
- Exemplos: Pode ser muito interessante disponibilizar exemplos de como consumir sua API. Podem ser exemplos desde como começar a usar a API até casos mais específicos de uso. Inclua bastante código e, se possível, coloque casos reais de consumidores.
- Changelog: Detalhe as últimas atualizações e como elas podem afetar os consumidores da API. Isso os ajudará a medir a estabilidade da API, sinalizando se as mudanças na API afetarão ou não a integração.
Sua API alcançará um patamar mais elevado ao inserir esses itens na documentação. Agora, quando os consumidores potenciais olharem para sua API, eles a encontrarão documentada de forma muito clara. Essas informações ajudam a criar credibilidade, a construir confiança a longo prazo e a aumentar o engajamento dos desenvolvedores.