.png){kind=small}
.png){kind=small}
A indústria de APIs se desenvolve e cresce em períodos de mudança: enquanto as necessidades do consumidor crescerem, vai crescer também a demanda sobre o provedor da API. Dessa maneira, o provedor deve sempre estar à frente na constante evolução tecnológica.Enquanto esse ciclo de mudança é positivo em alto nível, ele traz com ele alguns desafios únicos: como a de comunicar a mudança para seus usuários desenvolvedores. Seja para versionamento, retirada de endpoint, ou alguma outra mudança, usuários desenvolvedores no panorama moderno de APIs esperam uma parcela de tempo alocado e um método de comunicação totalmente endereçado.Hoje, vamos olhar para alguns desses métodos de comunicação e identificar por que a comunicação tradicional passiva ganha forças, como usada em versionamento de APIs, mas não provê uma para o problema apresentado. Vamos discutir 6 métodos para comunicar mudança de API, assim como apresentar algumas ressalvas quanto a diferentes modos de comunicação.
APIs se comunicam passivamente quando posta mudanças sem tentar notificar um público planejado; uma organização cria a informação e a coloca em uma localidade estática, esperando que usuários se importem o suficiente para que trombem com ela.Tal método é ineficiente por uma variedade de razões. Enquanto versionamento não é por si só uma sentença de morte para a API, sem um plano de comunicação em ação pode criar mais problemas que resolve. Pode resultar em usuários encontrando seus softwares e outros elementos sendo incompatíveis com um endpoint ou recurso previamente configurados. Em outras palavras, comunicação passiva como método de gerenciamento de mudanças único pode facilmente resultar em clientes insatisfeitos.A notificação devida pode adereçar isso, dando usuários tempo para garantir a configuração, mas o fardo do lado do cliente pode ser mais complexo que você pensa. O processo de verificar versão, fazer update em credenciais e integrar com as novas mudanças pode resultar em dedicação de tempo significativa. Quanto mais passiva for a comunicação para adereçar essas mudanças, maior é a responsabilidade colocada no usuário e claramente essa é uma mudança de responsabilidade inapropriada.O que podemos fazer então, para fazer a comunicação desses mudanças de maneira mais efetiva, melhor e por fim uma melhoria do básico, a comunicação passiva?
Uma das melhores coisas que podemos fazer quando o assunto é comunicar mudança é identificar quem é o usuário para cada um de nossos serviços, e adotar um método de comunicação de acordo com suas necessidades.Podemos pensar que APIs tem três tipos de usuários. Um usuário normal é simplesmente o mais básico utilizando as funções mais básicas. Acima deles, os super usuários requerem funções especiais e serviços mais complexos. Por fim, usuários internos utilizam a API em um ponto de vista interno, seja como parte do time de desenvolvimento ou como business partner.Após definirmos o usuário, nós podemos apontar para ele aspectos específicos da mudança que são servidos no microserviço que ele consome - isso pode evitar excesso de notificações no futuro. Além dos alertas específicos, aprender sobre os hábitos do consumidor das suas APIs pode ditar o que ficará em destaque nos seus anúncios de mudança.Por exemplo, se o usuário básico padrão utiliza o Twitter para engajar com o time de desenvolvimento, uma maneira de realizar a comunicação pode ser tão simple como um resumo via Twitter para esses usuários. Por outro lado, se nenhum dos seus super usuários ou usuários internos utilizam o Twitter, mas preferem usar o email, então a comunicação deve ocorrer por esse canal.
Agora que já definimos as guidelines iniciais para comunicar as mudanças, vamos olhar para alguns métodos de comunicação específicos. Nenhum desses métodos vai ser apropriado para todo caso de uso, assim sendo, é imprescindível que o desenvolvedor olhe para sua base de usuários e identifique a melhor opção para suas necessidades.ChangelogsUm método comum de comunicar mudança é por Changelog. Em sua essência, um changelog serve simplesmente como um método de tracking a longo prazo entre várias versões. Quando uma API faz update, cada mudança é notada como uma bifurcação da última versão, e isso serve como um método de comunicação não só para o que mudou, mas para por que e como modo também.Para que changelogs sejam realmente efetivos, entretanto, você deve adicionar alguns elementos à tradicional solução textual. Uma adição chave são links para changelogs anteriores em ordem cronológica, permitindo usuários a trabalhar de trás para frente e contextualizar mudanças.Um changelog deve ser considerado um método de comunicação, mas um elemento importante é considerar o método de atribuição do changelog. Changelogs ativos são quase sempre a melhor opção, ativamente mandando para usuários que utilizam os serviços. Changelogs passivos, no entanto, não são diferentes de uma comunicação passiva versionada, como conversamos acima.
Um método excelente e moderno de comunicação é por meio das redes sociais, mandando alertas para mudanças, e até usando redes sociais para responder as reclamações e necessidades de usuários.Porém, esse tipo de notificação deve ser passada por meio da própria conta de desenvolvedor, para que essa informação não seja perdida no meio de mensagens virtuais. Isso é especialmente importante quando provedores de APIs operam através de múltiplos campos e funções, como quando um consultor prover uma API para uma proposta de negócios secundária. Nesses caso, a separação é necessária.Entretanto, se não for possível realizar a separação, cada post da rede social deve conter seu update de notícias centralizado, para que ocorra o linking de uma notificação para outra. Por fim, redes sociais podem ser uma ferramenta muito forte, contato que utilizada de modo cuidadoso.
Utilizar serviços de emails automatizados podem efetivamente comunicar mudanças provendo um espaço amplo para notificação e descrição de mudanças. Dito isso, mandar email pode ser mais complicado que outras opções, devido a natureza do email. Changelogs e redes sociais são fundamentalmente opt-in. Email, entretanto, pode ocorrer sem a autorização do usuário.Dessa maneira, não assuma que todo usuário vai querer um update, especialmente se mudanças ocorrem diariamente. Falhar em adereçar esse requisito resulta em fadiga de notificações (que estamos querendo evitar). Disponibilize configurações de subscrição e notificação. Adicionalmente, proveja um método adequado de sair de tais emails, para garantir conformidade com as melhores práticas de comunicação
Um método ótimo para comunicar mudanças é utilizar ferramentas voltadas para o desenvolvedor. Algo simples como um dev log, um blog com várias documentações de desenvolvimentos ou escolhas feitas durante o lifecycle podem ser extremamente efetivos. Parte desse tipo de comunicação vem do uso do Portal dos Desenvolvedores, que utiliza uma representação de progresso de desenvolvimento para comunicar mudança.Um ótimo exemplo desse tipo de comunicação é o MailChimp. A metodologia deles utiliza uma barra vermelha que enche quando o desenvolvimento for concluído, e provê links para as mudanças quando elas entram na plataforma. Esse tipo de portal de desenvolvedores é ótimo para contextualizar mudança e desenvolvimento durante o tempo, assim como o efeito da mudança no sistema inteiro
O MailChimp mostra as mudanças em sua API no topo do seu Portal de Desenvolvedores
Uma API RESTful com um bom design pode por si só servir como serviço de notificação. Hypermedia tem sido colocada como um pré-requisito para uma API realmente RESTful. Que sorte, pois Hypermedia é um pré-requisito para efetiva comunicação de mudança também.Como um setup de Hypermedia correto, um objeto pode ser passado para o usuário que não só notifica o usuário de uma mudança, mas também provê um link para o changelog, para a rede social, e até para um novo endpoint na documentação. Hypermedia serve como notificação para o usuário de vários níveis, e exige esforço para documentar em todos os níveis
Em alguns casos, a diferença entre cada mudança pode não ser suficiente para garantir comunicação nos métodos previamente discutidos. Um exemplo é o Canary Release. Nesse approach, versionamento é evitado realizando exposição de novas builds através do tempo, apresentando uma transição mais simples e limpa para o usuário em questão. Infelizmente, isso significa que a notificação de versão é necessária, mas tais notificações podem não ser adequadas para todos os usuários.Nesses casos, as notificações devem servir como um serviço secundário, ao invés de um aviso de nova funcionalidade - a transição deve ser completamente desatada. O usuário pode ficar ciente da possibilidade de uma nova versão, mas uma mudança brusca não deveria ser descoberta vendo o changelog.
Enquanto é tentador ficar com o que é testado e comprovado, existem várias maneiras mais modernas e eficientes que mostrar um número de versão e uma notificação via contato na API.Como parte desse approach moderno, devemos notar que uma metodologia única não é sempre a melhor escolha. Com um conjunto de escolhas e uma variedade de canais para comunicarmos a mudança, uma combinação pode ser alcançada para coordenar updates para vários grupos de usuários com conteúdos de comunicação customizado para cada ferramenta e grupo de usuários utilizando a ferramenta.Por fim, como alguém escolhe notificar seus usuários de uma mudança pode ser altamente variável. O que realmente importa não é a minúcia de como você notifica, mas notificar de uma maneira útil e apropriada para cada tipo e grupo de usuário existente. Notificar corretamente é muito importante, e pode fazer muita diferença na User Experience a ponto de mudar o user flow e mudar a percepção dos clientes sobre sua API.
