Artigos
Como criar um catálogo de API interno com o Atlassian Compass
KATIE SILVER
GERENTE DE PRODUTO PRINCIPAL, ATLASSIAN
Resumo executivo
Resumo executivo aqui
Tempo
Quatro minutos de leitura. Menos de 10 minutos para configurar o Compass.
Público-alvo:
Pessoas que fazem parte de uma equipe de entrega de software e usam APIs. Útil para desenvolvedores, engenheiros e outros.
Pré-requisitos
- Obtenha o Compass: o teste é gratuito e leva poucos minutos para começar.
Criar um catálogo de API preciso é um desafio
Na última década, trocamos grandes monólitos por microsserviços, arquiteturas distribuídas e equipes autônomas. Os benefícios são evidentes, mas as consequências também são: testes e compiladores com tipagem usados para manter todas as partes de uma base de código grande funcionando bem juntas. Hoje, a integração depende das APIs, e não está claro se tudo vai funcionar junto após a implantação.
Sabemos que os desenvolvedores trabalham mais rápido e as equipes lançam produtos melhores quando todos entendem como as APIs funcionam e quando elas mudam. O rastreamento e a manutenção dessa documentação que são difíceis.
Cada organização está em um nível diferente de maturidade quando se trata de mapear seus serviços. Em algumas equipes, as conversas no Slack mantêm o alinhamento entre os produtores e consumidores de API. Em outras, a forma como cada API funciona é documentada quando o serviço é criado, mas nunca atualizada. Se você tem bons processos ou ferramentas implementados, toda API é documentada e suas mudanças são comunicadas para as outras partes interessadas sem intervenção manual.
Onde quer que você esteja nessa jornada, o Compass, a nova plataforma da Atlassian para desenvolvedores, pode ajudar.
Documentação de API centralizada com o Compass
Quando se trata de microsserviços, onde a documentação da API deve ficar? Só porque desenvolvemos e implantamos nossos serviços em lugares separados, isso não significa que queremos que cada um tenha seu próprio site de documentação hospedado, ou um arquivo da OpenAPI em algum local obscuro. As equipes querem reunir todas essas informações em um formato pesquisável sem um esforço interno massivo para criar um registro de API.
Com o Compass, você unifica toda a sua documentação de API em uma hora, não em uma semana ou um trimestre. Esqueça o upload manual da documentação sempre que fizer alterações. Você só precisa conectar seu SCM (Bitbucket, GitHub ou GitLab) ao Compass.
Em alguns minutos, o Compass procura arquivos da OpenAPI em todos os seus repositórios e os publica no seu catálogo. As APIs de todas as suas equipes ficam centralizadas e pesquisáveis na mesma hora.
Descoberta e integração com uma API
Suponha que um desenvolvedor assuma um ticket para criar um novo fluxo de reembolso. Ele sabe que precisa encontrar a API certa para processar um reembolso, mas não sabe por onde começar. Em muitas empresas, o desenvolvedor perguntaria no Slack, podendo ter que esperar horas para um colega do outro lado do mundo tirar suas dúvidas sobre qual API usar. Equipes com o Compass contam com autoatendimento. O desenvolvedor pode pesquisar endpoints de API e encontrar as informações exatas de que precisa direto no Compass em apenas alguns segundos. Isso acelera o processo de esclarecimento, e a equipe responsável pela API em questão sofre menos interrupções.
Receba notificações sobre alterações na API
Quando se trata de microsserviços, a implantação dos serviços é autônoma e, às vezes, muda de tal forma que é importante os consumidores ficarem sabendo. Por sorte, o Compass não apenas conhece a documentação da sua API, mas também sabe como ela muda ao longo do tempo. Toda vez que um colega faz merge de uma pull request que atualiza a documentação da sua API, a versão da documentação no Compass também é atualizada. Assim, a versão que os desenvolvedores veem no Compass é sempre a API mais atualizada.
As alterações históricas também aparecem na página de registro de alterações para você ver quando mudanças importantes aconteceram.
Quando os desenvolvedores têm a documentação necessária, o código é entregue mais rápido
Em uma pesquisa recente do Postman com desenvolvedores de API, 52% dos desenvolvedores disseram que o maior problema ao trabalhar com APIs era a falta de documentação. Isso afeta o ritmo de desenvolvimento, dificulta a integração de novos engenheiros e torna o software menos confiável.
Se você tivesse que criar seu próprio catálogo interno de API, seria um projeto enorme, com muitas variáveis. Fizemos todo esse trabalho para você: tenha um hub centralizado de documentação em poucos minutos.
Dê à sua equipe as informações de que ela precisa e aproveite um lançamento mais rápido 🚀.