Flex Gateway Novo
API Governance Novo
Monitoring API ManagerComo as APIs foram criadas para serem consumidas, é importante garantir que o cliente ou o consumidor possa implementar uma API rapidamente e entender o que está acontecendo com ela. Infelizmente, muitas APIs tornam a implementação extremamente difícil, o que frustra o seu próprio objetivo. Conforme você cria sua API, você deve garantir não só a apresentação de uma documentação informativa da API para ajudar seus desenvolvedores a integrar/depurar conexões, mas também exibir dados relevantes sempre que um usuário faz uma chamada — especialmente uma chamada que apresenta falha.
Apesar de ser extremamente importante ter uma resposta do corpo do texto coerente e bem formatada na documentação da API (o ideal é que ela seja algo desserializado, iterado e compreendido), também é uma boa opção oferecer aos desenvolvedores referências rápidas sobre o que aconteceu com a chamada, inclusive o uso de códigos de status. E, em caso de falha, talvez você queira apresentar mensagens de erro descritivas que informem ao cliente não só o que deu errado, mas também como corrigir o erro.
Quando você estiver planejando sua API, precisará saber como manterá a documentação dela. Essa é uma área que não deve ser subestimada, já que é comprovadamente o ponto crucial de usabilidade para a maioria das APIs públicas. Embora a documentação possa parecer uma tarefa fácil e rápida, a maioria das empresas informará que ela é um dos maiores desafios e responsabilidades quando se trata de manter as APIs.
A documentação é um dos fatores mais importantes para determinar o sucesso de uma API, já que uma documentação sólida e fácil de entender facilita muito a implementação de APIs, enquanto uma documentação confusa, fora de sincronia, incompleta ou complexa gera uma aventura indesejada — que geralmente faz com que desenvolvedores frustrados utilizem as soluções de um concorrente.
O desafio é que, além de a documentação precisar ter aparência consistente, ela também deve ser consistente com a funcionalidade da API e atualizada com as mudanças mais recentes. Sua documentação também deve ser fácil de entender e ser escrita para desenvolvedores (geralmente, por uma equipe experiente de documentação). Até recentemente, as soluções de documentação incluíam caros sistemas de terceiros, o uso do Sistema de gerenciamento de conteúdo (CMS) existente ou, até mesmo, um CMS dedicado com base em software de código aberto, como Drupal/WordPress. Infelizmente, apesar de as soluções específicas para documentação de APIs oferecerem consistência em relação à aparência da sua API (algo que é mais difícil manter com um CMS), elas ainda dependem de esforços manuais do desenvolvedor (se forem derivadas do código) ou de uma equipe de documentação para mantê-las atualizadas.
No entanto, com a expansão das especificações abertas, como RAML — e as comunidades que a cercam —, a documentação se tornou muito mais fácil. Em vez de tentar analisar comentários de código e fazer com que os desenvolvedores escrevam descrições em linha (geralmente), a equipe de documentação ainda consegue apresentar uma documentação descritiva na especificação da API, com todos os parâmetros/exemplos de código já incluídos, o que facilita a transição para a documentação. E, com a explosão das empresas de software como serviço (SaaS) de documentação de APIs que utilizam e expandem essas especificações, nunca foi tão fácil ou barato criar uma documentação e um API portal eficazes.
Uma boa documentação deve servir como referência e como uma fonte de instruções, permitindo que os desenvolvedores obtenham rapidamente as informações que estão procurando e, ao ler a documentação, entendam como integrar o recurso/método que estão procurando.
Dessa forma, uma boa documentação deve ser clara e concisa, mas também visual, apresentando os seguintes elementos:
Um dos principais benefícios do desenvolvimento orientado por especificações é que, em vez de ter que depender de fornecedores caros e complexos — ou de tentar criar uma solução pontual de documentação de APIs com base em um CMS como WordPress ou Drupal —, as especificações como RAML, Swagger e API Blueprint têm sólidas comunidades de código aberto que as cercam e que oferecem para uso ferramentas de documentação criadas previamente. Cada uma delas oferece seu próprio conjunto de ferramentas exclusivo; mas, neste relatório, nós nos concentraremos nas ferramentas disponíveis na comunidade de RAML. A comunidade de RAML já reuniu analisadores de várias linguagens diferentes, como Java, Ruby, PHP e Node, bem como scripts completos para gerenciar a documentação de APIs e, ao mesmo tempo, oferecer ambientes interativos como API Console e API Notebook. Essas ferramentas ajudam você a apresentar uma documentação como exibido nos exemplos de ReadMe.io, Constant Contact e Twilio acima, com pouco ou nenhum trabalho de sua parte (a não ser a instalação e, obviamente, a definição da RAML). Aqui, você pode encontrar várias ferramentas e fazer download delas livremente.
À medida que as empresas reconhecem o valor cada vez maior das APIs, elas estão começando a desenvolver centenas delas. A capacidade de publicá-las devidamente de uma forma em que o desenvolvedor que as consome possa encontrá-las, pesquisá-las e entendê-las facilmente será um aspecto importante que avançará ou prejudicará todo o seu programa de APIs. Uma boa documentação é uma parte importante disso.