Criando, evoluindo e fazendo o controle de versão de APIs e de contratos de microsserviçosCreating, evolving, and versioning microservice APIs and contracts

Uma API de microsserviço é um contrato entre o serviço e seus clientes.A microservice API is a contract between the service and its clients. Você poderá evoluir um microsserviço de forma independente apenas se você não precisar interromper seu contrato de API, que é o motivo pelo qual o contrato é tão importante.You'll be able to evolve a microservice independently only if you do not break its API contract, which is why the contract is so important. Se você alterar o contrato, isso afetará seus aplicativos cliente ou seu Gateway de API.If you change the contract, it will impact your client applications or your API Gateway.

A natureza da definição de API depende do protocolo que você está usando.The nature of the API definition depends on which protocol you're using. Por exemplo, se você estiver usando mensagens (como AMQP), a API consistirá nos tipos de mensagem.For instance, if you're using messaging (like AMQP), the API consists of the message types. Se você estiver usando serviços HTTP e RESTful, a API consistirá nas URLs e nos formatos JSON de solicitação e de resposta.If you're using HTTP and RESTful services, the API consists of the URLs and the request and response JSON formats.

No entanto, mesmo se você estiver em dúvida sobre seu contrato inicial, uma API de serviço precisará ser alterada com o tempo.However, even if you're thoughtful about your initial contract, a service API will need to change over time. Quando isso acontecer – e, principalmente, se a API for uma API pública consumida por vários aplicativos cliente – normalmente não será possível forçar todos os clientes a atualizarem para seu novo contrato de API.When that happens—and especially if your API is a public API consumed by multiple client applications — you typically can't force all clients to upgrade to your new API contract. Geralmente, é necessário implantar novas versões de um serviço de forma incremental de maneira que versões novas e antigas de um contrato de serviço estejam em execução simultaneamente.You usually need to incrementally deploy new versions of a service in a way that both old and new versions of a service contract are running simultaneously. Portanto, é importante ter uma estratégia para o controle de versão do serviço.Therefore, it's important to have a strategy for your service versioning.

Quando as alterações na API forem pequenas, como adicionar atributos ou parâmetros à sua API, os clientes que usam uma API mais antiga devem mudar e trabalhar com a nova versão do serviço.When the API changes are small, like if you add attributes or parameters to your API, clients that use an older API should switch and work with the new version of the service. Talvez seja possível fornecer valores padrão para quaisquer atributos ausentes que sejam necessários, e os clientes talvez podem ignorar quaisquer atributos de resposta extra.You might be able to provide default values for any missing attributes that are required, and the clients might be able to ignore any extra response attributes.

No entanto, às vezes, é necessário fazer alterações importantes e incompatíveis em uma API de serviço.However, sometimes you need to make major and incompatible changes to a service API. Como talvez não seja possível forçar serviços ou aplicativos cliente a serem atualizados imediatamente para a nova versão, um serviço deve dar suporte a versões mais antigas da API por algum período.Because you might not be able to force client applications or services to upgrade immediately to the new version, a service must support older versions of the API for some period. Se você estiver usando um mecanismo baseado em HTTP como REST, uma abordagem deverá inserir o número de versão da API na URL ou no cabeçalho HTTP.If you're using an HTTP-based mechanism such as REST, one approach is to embed the API version number in the URL or into an HTTP header. Em seguida, é possível decidir entre implementar ambas as versões do serviço simultaneamente dentro da mesma instância de serviço ou implantar instâncias diferentes que lidam com uma versão da API.Then you can decide between implementing both versions of the service simultaneously within the same service instance, or deploying different instances that each handle a version of the API. Uma boa abordagem para isso é o padrão mediador (por exemplo, biblioteca MediatR) para desacoplar as diferentes versões de implementação em manipuladores independentes.A good approach for this is the Mediator pattern (for example, MediatR library) to decouple the different implementation versions into independent handlers.

Por fim, se você estiver usando uma arquitetura REST, o Hypermedia será a melhor solução para controlar a versão de seus serviços e permitir APIs capazes de evoluir.Finally, if you're using a REST architecture, Hypermedia is the best solution for versioning your services and allowing evolvable APIs.

Recursos adicionaisAdditional resources