Criação, evolução e controle de versão de APIs e contratos de microsserviço

Uma API de microsserviço é um contrato entre o serviço e seus clientes. Você poderá desenvolver um microsserviço de forma independente somente se não quebrar o contrato de API, razão pela qual o contrato é tão importante. Se você alterar o contrato, ele afetará seus aplicativos cliente ou seu Gateway de API.

A natureza da definição da API depende de qual protocolo você está usando. Por exemplo, se você estiver usando mensagens, como AMQP, a API consistirá nos tipos de mensagem. Se você estiver usando serviços HTTP e RESTful, a API consistirá nas URLs e nos formatos JSON de solicitação e resposta.

No entanto, mesmo sendo cuidadoso com seu contrato inicial, uma API de serviço precisará mudar ao longo do tempo. Quando isso acontece — e especialmente se sua API é uma API pública consumida por vários aplicativos cliente — você normalmente não pode forçar todos os clientes a atualizar para seu novo contrato de API. Normalmente, você precisa implantar novas versões de um serviço de forma que as versões antigas e novas de um contrato de serviço sejam executadas simultaneamente. Portanto, é importante ter uma estratégia para o controle de versão do serviço.

Quando as alterações de API são pequenas, como se você adicionasse atributos ou parâmetros à API, os clientes que usam uma API mais antiga deverão alternar e trabalhar com a nova versão do serviço. Você pode fornecer valores padrão para todos os atributos ausentes necessários, e os clientes podem ignorar quaisquer atributos de resposta extras.

No entanto, às vezes, você precisa fazer alterações importantes e incompatíveis em uma API de serviço. Como você pode não conseguir forçar aplicativos ou serviços cliente a atualizar imediatamente para a nova versão, um serviço deve dar suporte a versões mais antigas da API por algum período. Se você estiver usando um mecanismo baseado em HTTP, como REST, uma abordagem é inserir o número de versão da API na URL ou em um cabeçalho HTTP. Em seguida, você pode decidir entre implementar ambas as versões do serviço simultaneamente na mesma instância de serviço ou implantar instâncias diferentes que cada uma manipula uma versão da API. Uma boa abordagem para essa funcionalidade é o padrão mediador (por exemplo, biblioteca MediatR) para desacoplar as diferentes versões de implementação em manipuladores independentes.

Por fim, se você estiver usando uma arquitetura REST, o Hypermedia será a melhor solução para controle de versão de seus serviços e permitir APIs em evolução.

Recursos adicionais

• Scott Hanselman. Controle de versão da API Web RESTful do ASP.NET Core facilitado
  https://www.hanselman.com/blog/ASPNETCoreRESTfulWebAPIVersioningMadeEasy.aspx

• Controle de versão de uma API Web RESTful
  https://learn.microsoft.com/azure/architecture/best-practices/api-design#versioning-a-restful-web-api

• Roy Fielding. Controle de versão, Hipermedia e REST
  https://www.infoq.com/articles/roy-fielding-on-versioning