{"id":45,"date":"2023-09-24T11:27:21","date_gmt":"2023-09-24T14:27:21","guid":{"rendered":"https:\/\/dotnetdicas.com.br\/?p=45"},"modified":"2023-12-10T13:02:06","modified_gmt":"2023-12-10T16:02:06","slug":"domine-o-controle-de-versao-em-apis-net","status":"publish","type":"post","link":"https:\/\/dotnetdicas.com.br\/?p=45","title":{"rendered":"Domine o Controle de Vers\u00e3o em APIs .Net"},"content":{"rendered":"

Ol\u00e1, Devs! Vamos entender controle de vers\u00e3o no .Net?<\/span><\/p>\n

Em um mundo dominado por sistemas interconectados e aplica\u00e7\u00f5es que constantemente comunicam entre si, a gest\u00e3o e evolu\u00e7\u00e3o das interfaces de programa\u00e7\u00e3o de aplica\u00e7\u00f5es (APIs) \u00e9 crucial, especialmente quando se refere \u00e0 API do .Net. Em ambientes de desenvolvimento modernos, o controle de vers\u00e3o desempenha um papel essencial, garantindo que as modifica\u00e7\u00f5es feitas na API n\u00e3o comprometam as aplica\u00e7\u00f5es existentes que a utilizam.<\/span><\/p>\n

 <\/p>\n

1. Import\u00e2ncia do controle de vers\u00e3o<\/span><\/h3>\n

Os desenvolvedores geralmente evoluem uma API primeiramente porque querem introduzir novas funcionalidades ou por outro lado, melhorar sua performance. No entanto, se eles n\u00e3o gerenciarem as altera\u00e7\u00f5es corretamente, incompatibilidades podem surgir e consequentemente prejudicar sistemas em produ\u00e7\u00e3o. Dessa forma, no contexto da API do .Net, precisamos de um mecanismo eficiente de controle de vers\u00e3o.<\/span><\/p>\n

2. M\u00e9todos tradicionais e seus desafios<\/span><\/h3>\n

Tradicionalmente, desenvolvedores implementam o controle de vers\u00e3o em APIs atrav\u00e9s do versionamento por URL ou usando cabe\u00e7alhos HTTP. No primeiro m\u00e9todo, eles especificam a vers\u00e3o diretamente na URL da API, como em: api\/v1\/recurso<\/strong>. No segundo, eles indicam a vers\u00e3o em um cabe\u00e7alho HTTP, como Accept-Version: v1.0<\/strong>.<\/span><\/p>\n

Por\u00e9m, desenvolvedores enfrentam desafios frequentemente. Quando eles incorporam a vers\u00e3o da API \u00e0 URL, mudan\u00e7as na estrutura da API podem resultar em URLs desorganizadas. J\u00e1 o uso de cabe\u00e7alhos pode confundir desenvolvedores menos experientes.<\/span><\/p>\n

3. Solu\u00e7\u00f5es que o .Net oferece<\/span><\/h3>\n

Na API do .Net, os desenvolvedores encontram mecanismos refinados para controlar as vers\u00f5es. O .Net introduziu uma biblioteca espec\u00edfica, a Microsoft.AspNetCore.Mvc.Versioning<\/strong><\/a>, para simplificar esse processo.<\/span><\/p>\n

Ao usar essa biblioteca, os desenvolvedores podem especificar a vers\u00e3o da API atrav\u00e9s de um par\u00e2metro de consulta, um cabe\u00e7alho personalizado ou diretamente no caminho da URL. Por exemplo, eles podem fazer uma solicita\u00e7\u00e3o assim: api\/recurso?api-version=2.0<\/strong>.<\/span><\/p>\n

Essa abordagem oferece vantagens not\u00e1veis. Primeiramente, ela estabelece um padr\u00e3o uniforme, tornando o versionamento transparente e consistente. Al\u00e9m disso, com essa biblioteca, diferentes vers\u00f5es da API podem coexistir no mesmo endere\u00e7o, facilitando uma transi\u00e7\u00e3o suave entre elas.<\/span><\/p>\n

4. Vamos ver um exemplo?<\/span><\/h3>\n

Considere o desenvolvimento de uma API que gerencia informa\u00e7\u00f5es de estudantes. Na primeira vers\u00e3o, tem-se um m\u00e9todo para obter o nome do estudante. Com o tempo, surge a necessidade de expandir essa funcionalidade, adicionando um m\u00e9todo para obter a m\u00e9dia de notas do estudante.<\/span><\/p>\n

Sem o controle adequado de vers\u00e3o, essa nova funcionalidade poderia comprometer sistemas que dependem da vers\u00e3o anterior da API. No entanto, com o uso da biblioteca Microsoft.AspNetCore.Mvc.Versioning<\/strong><\/a>, \u00e9 poss\u00edvel manter ambas as vers\u00f5es funcionando simultaneamente.<\/span><\/p>\n

Como fa\u00e7o?<\/span><\/h4>\n

\u2713<\/strong> Primeiramente, voc\u00ea ter\u00e1 que adicionar a biblioteca Microsoft.AspNetCore.Mvc.Versioning<\/em> ao projeto. Isso pode ser feito via NuGet Package Manager<\/em> ou via linha de comando:<\/span><\/p>\n

\"Instala\u00e7\u00e3o<\/p>\n

\u2713<\/strong> Depois de adicionada, configure o servi\u00e7o:<\/span><\/p>\n

\"Configura\u00e7\u00e3o<\/p>\n

Aqui, configuramos a API para ter uma vers\u00e3o padr\u00e3o de 1.0<\/strong>. Se nenhuma vers\u00e3o for especificada na solicita\u00e7\u00e3o, ela assumir\u00e1 1.0<\/strong> como padr\u00e3o. A op\u00e7\u00e3o ReportApiVersions<\/strong> informar\u00e1 aos clientes quais vers\u00f5es est\u00e3o dispon\u00edveis.<\/span><\/p>\n

\u2713<\/strong> Crie a Controller de estudantes<\/span><\/p>\n

    \n
  • Para vers\u00e3o 1 da API:<\/span><\/li>\n<\/ul>\n

    \"Vers\u00e3o<\/p>\n

    No exemplo acima, uma requisi\u00e7\u00e3o GET para \/api\/students\/1\/name?api-version=1.0<\/code> retornar\u00e1 “Estudante 1: Jo\u00e3o Silva”.<\/span><\/p>\n

      \n
    • Para vers\u00e3o 2 da API:<\/span><\/li>\n<\/ul>\n

      \"Vers\u00e3o<\/p>\n

      Agora, uma requisi\u00e7\u00e3o GET para \/api\/students\/1\/averageGrade?api-version=2.0<\/code> retornar\u00e1 “Estudante 1: M\u00e9dia 8.5”.<\/span><\/p>\n

       <\/p>\n

      Posso fazer de outras formas?<\/span><\/h4>\n

      Sim, voc\u00ea pode decorar a Controller com v\u00e1rias vers\u00f5es de API usando a anota\u00e7\u00e3o\u00a0 [ApiVersion]<\/strong><\/span> v\u00e1rias vezes. Isso significa que a controller (ou a a\u00e7\u00e3o, dependendo de onde voc\u00ea coloca a anota\u00e7\u00e3o) pode atender a m\u00faltiplas vers\u00f5es da API.<\/span><\/span><\/p>\n

      Se voc\u00ea quiser que o m\u00e9todo GetStudentName<\/strong> esteja dispon\u00edvel em ambas as vers\u00f5es “1.0” e “2.0”, voc\u00ea pode fazer o seguinte:<\/span><\/p>\n

      \"Vers\u00f5es<\/p>\n

      Neste exemplo, o m\u00e9todo GetStudentName<\/strong> estar\u00e1 dispon\u00edvel para ambas api-version=1.0<\/strong> e api-version=2.0<\/strong> .<\/span><\/p>\n

      Se voc\u00ea quiser ser ainda mais granular e especificar vers\u00f5es em n\u00edvel de a\u00e7\u00e3o (em vez da controller), voc\u00ea pode fazer isso tamb\u00e9m. Por exemplo, voc\u00ea pode ter um m\u00e9todo na controller que \u00e9 espec\u00edfico para uma vers\u00e3o e outro m\u00e9todo para outra vers\u00e3o:<\/span><\/p>\n

      \"Vers\u00e3o<\/p>\n

      Neste cen\u00e1rio, o comportamento de GetStudentName<\/strong> pode variar dependendo da vers\u00e3o da API solicitada pelo cliente.<\/span><\/p>\n


      \nExiste tamb\u00e9m, a anota\u00e7\u00e3o [MapToApiVersion]<\/strong> que \u00e9 usada para indicar explicitamente que uma a\u00e7\u00e3o espec\u00edfica em uma controller deve responder apenas a uma determinada vers\u00e3o da API, mesmo se o controlador em si estiver decorado para atender a v\u00e1rias vers\u00f5es.<\/span><\/p>\n

      Vamos ver como isso se aplica no contexto do nosso exemplo anterior:<\/span><\/p>\n

      \"MapToApiVersion\"<\/p>\n

      Neste exemplo, a a\u00e7\u00e3o GetVersionSpecificInfo<\/strong> s\u00f3 responder\u00e1 \u00e0s solicita\u00e7\u00f5es que especificam api-version=2.0<\/strong>,\u00a0 gra\u00e7as \u00e0 anota\u00e7\u00e3o [MapToApiVersion(“2.0”)]<\/strong>. No\u00a0 entanto, o m\u00e9todo GetStudentName<\/strong> ainda est\u00e1 dispon\u00edvel para ambas as vers\u00f5es “1.0” e “2.0”, j\u00e1 que ele n\u00e3o possui uma anota\u00e7\u00e3o MapToApiVersion<\/strong> e a controller em si suporta ambas as vers\u00f5es.<\/span><\/p>\n

      A anota\u00e7\u00e3o [MapToApiVersion]<\/strong> fornece uma granularidade adicional, permitindo que os desenvolvedores definam comportamentos espec\u00edficos para vers\u00f5es diferentes dentro da mesma controller.<\/span><\/p>\n

      5. Conclus\u00e3o<\/span><\/h3>\n

      O uso do versionamento, inicialmente, permite a coexist\u00eancia dessas duas vers\u00f5es da API no mesmo endere\u00e7o. Dessa forma, sistemas legados continuem a funcionar normalmente, enquanto novos sistemas ou sistemas atualizados podem optar por utilizar a vers\u00e3o mais recente da API.<\/span><\/p>\n

      Isso ilustra o poder e a flexibilidade do controle de vers\u00e3o na API do .NET, permitindo que os desenvolvedores evoluam suas APIs sem medo de quebrar sistemas existentes.<\/span><\/p>\n

       <\/p>\n

      Legal n\u00e9?!<\/span><\/p>\n","protected":false},"excerpt":{"rendered":"

      Ol\u00e1, Devs! Vamos entender controle de vers\u00e3o no .Net? Em um mundo dominado por sistemas interconectados e aplica\u00e7\u00f5es que constantemente comunicam entre si, a gest\u00e3o e evolu\u00e7\u00e3o das interfaces de programa\u00e7\u00e3o de aplica\u00e7\u00f5es (APIs) \u00e9 crucial, especialmente quando se refere \u00e0 API do .Net. Em ambientes de desenvolvimento modernos, o controle de vers\u00e3o desempenha um […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[],"yoast_head":"\nDomine o Controle de Vers\u00e3o em APIs .Net - DotNetDicas - C\u00f3digo forte, Carreira mais forte<\/title>\n<meta name=\"description\" content=\"O controle de vers\u00e3o desempenha um papel essencial, garantindo que as modifica\u00e7\u00f5es feitas na API n\u00e3o comprometam as aplica\u00e7\u00f5es existentes...\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/dotnetdicas.com.br\/?p=45\" \/>\n<meta property=\"og:locale\" content=\"pt_BR\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Domine o Controle de Vers\u00e3o em APIs .Net - DotNetDicas - C\u00f3digo forte, Carreira mais forte\" \/>\n<meta property=\"og:description\" content=\"O controle de vers\u00e3o desempenha um papel essencial, garantindo que as modifica\u00e7\u00f5es feitas na API n\u00e3o comprometam as aplica\u00e7\u00f5es existentes...\" \/>\n<meta property=\"og:url\" content=\"https:\/\/dotnetdicas.com.br\/?p=45\" \/>\n<meta property=\"og:site_name\" content=\"DotNetDicas - C\u00f3digo forte, Carreira mais forte\" \/>\n<meta property=\"article:published_time\" content=\"2023-09-24T14:27:21+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2023-12-10T16:02:06+00:00\" \/>\n<meta property=\"og:image\" content=\"http:\/\/dotnetdicas.com.br\/wp-content\/uploads\/2023\/09\/pkgversiooning-300x20.png\" \/>\n<meta name=\"author\" content=\"L\u00facio Torres\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Escrito por\" \/>\n\t<meta name=\"twitter:data1\" content=\"L\u00facio Torres\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. tempo de leitura\" \/>\n\t<meta name=\"twitter:data2\" content=\"7 minutos\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/dotnetdicas.com.br\/?p=45\",\"url\":\"https:\/\/dotnetdicas.com.br\/?p=45\",\"name\":\"Domine o Controle de Vers\u00e3o em APIs .Net - DotNetDicas - C\u00f3digo forte, Carreira mais forte\",\"isPartOf\":{\"@id\":\"https:\/\/dotnetdicas.com.br\/#website\"},\"datePublished\":\"2023-09-24T14:27:21+00:00\",\"dateModified\":\"2023-12-10T16:02:06+00:00\",\"author\":{\"@id\":\"https:\/\/dotnetdicas.com.br\/#\/schema\/person\/368975f3d3f2d0c3c1d7b176c555b3fa\"},\"description\":\"O controle de vers\u00e3o desempenha um papel essencial, garantindo que as modifica\u00e7\u00f5es feitas na API n\u00e3o comprometam as aplica\u00e7\u00f5es existentes...\",\"breadcrumb\":{\"@id\":\"https:\/\/dotnetdicas.com.br\/?p=45#breadcrumb\"},\"inLanguage\":\"pt-BR\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/dotnetdicas.com.br\/?p=45\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/dotnetdicas.com.br\/?p=45#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"In\u00edcio\",\"item\":\"https:\/\/dotnetdicas.com.br\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Domine o Controle de Vers\u00e3o em APIs .Net\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/dotnetdicas.com.br\/#website\",\"url\":\"https:\/\/dotnetdicas.com.br\/\",\"name\":\"DotNetDicas - C\u00f3digo forte, Carreira mais forte\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/dotnetdicas.com.br\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"pt-BR\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/dotnetdicas.com.br\/#\/schema\/person\/368975f3d3f2d0c3c1d7b176c555b3fa\",\"name\":\"L\u00facio Torres\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"pt-BR\",\"@id\":\"https:\/\/dotnetdicas.com.br\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/c4d33f0feb1d62f7769da1983149ca69?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/c4d33f0feb1d62f7769da1983149ca69?s=96&d=mm&r=g\",\"caption\":\"L\u00facio Torres\"},\"sameAs\":[\"https:\/\/dotnetdicas.com.br\"],\"url\":\"https:\/\/dotnetdicas.com.br\/?author=2\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Domine o Controle de Vers\u00e3o em APIs .Net - DotNetDicas - C\u00f3digo forte, Carreira mais forte","description":"O controle de vers\u00e3o desempenha um papel essencial, garantindo que as modifica\u00e7\u00f5es feitas na API n\u00e3o comprometam as aplica\u00e7\u00f5es existentes...","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/dotnetdicas.com.br\/?p=45","og_locale":"pt_BR","og_type":"article","og_title":"Domine o Controle de Vers\u00e3o em APIs .Net - DotNetDicas - C\u00f3digo forte, Carreira mais forte","og_description":"O controle de vers\u00e3o desempenha um papel essencial, garantindo que as modifica\u00e7\u00f5es feitas na API n\u00e3o comprometam as aplica\u00e7\u00f5es existentes...","og_url":"https:\/\/dotnetdicas.com.br\/?p=45","og_site_name":"DotNetDicas - C\u00f3digo forte, Carreira mais forte","article_published_time":"2023-09-24T14:27:21+00:00","article_modified_time":"2023-12-10T16:02:06+00:00","og_image":[{"url":"http:\/\/dotnetdicas.com.br\/wp-content\/uploads\/2023\/09\/pkgversiooning-300x20.png"}],"author":"L\u00facio Torres","twitter_card":"summary_large_image","twitter_misc":{"Escrito por":"L\u00facio Torres","Est. tempo de leitura":"7 minutos"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/dotnetdicas.com.br\/?p=45","url":"https:\/\/dotnetdicas.com.br\/?p=45","name":"Domine o Controle de Vers\u00e3o em APIs .Net - DotNetDicas - C\u00f3digo forte, Carreira mais forte","isPartOf":{"@id":"https:\/\/dotnetdicas.com.br\/#website"},"datePublished":"2023-09-24T14:27:21+00:00","dateModified":"2023-12-10T16:02:06+00:00","author":{"@id":"https:\/\/dotnetdicas.com.br\/#\/schema\/person\/368975f3d3f2d0c3c1d7b176c555b3fa"},"description":"O controle de vers\u00e3o desempenha um papel essencial, garantindo que as modifica\u00e7\u00f5es feitas na API n\u00e3o comprometam as aplica\u00e7\u00f5es existentes...","breadcrumb":{"@id":"https:\/\/dotnetdicas.com.br\/?p=45#breadcrumb"},"inLanguage":"pt-BR","potentialAction":[{"@type":"ReadAction","target":["https:\/\/dotnetdicas.com.br\/?p=45"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/dotnetdicas.com.br\/?p=45#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"In\u00edcio","item":"https:\/\/dotnetdicas.com.br\/"},{"@type":"ListItem","position":2,"name":"Domine o Controle de Vers\u00e3o em APIs .Net"}]},{"@type":"WebSite","@id":"https:\/\/dotnetdicas.com.br\/#website","url":"https:\/\/dotnetdicas.com.br\/","name":"DotNetDicas - C\u00f3digo forte, Carreira mais forte","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/dotnetdicas.com.br\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"pt-BR"},{"@type":"Person","@id":"https:\/\/dotnetdicas.com.br\/#\/schema\/person\/368975f3d3f2d0c3c1d7b176c555b3fa","name":"L\u00facio Torres","image":{"@type":"ImageObject","inLanguage":"pt-BR","@id":"https:\/\/dotnetdicas.com.br\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/c4d33f0feb1d62f7769da1983149ca69?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/c4d33f0feb1d62f7769da1983149ca69?s=96&d=mm&r=g","caption":"L\u00facio Torres"},"sameAs":["https:\/\/dotnetdicas.com.br"],"url":"https:\/\/dotnetdicas.com.br\/?author=2"}]}},"_links":{"self":[{"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=\/wp\/v2\/posts\/45"}],"collection":[{"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=45"}],"version-history":[{"count":25,"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=\/wp\/v2\/posts\/45\/revisions"}],"predecessor-version":[{"id":153,"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=\/wp\/v2\/posts\/45\/revisions\/153"}],"wp:attachment":[{"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=45"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=45"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/dotnetdicas.com.br\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=45"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}