{"id":1747,"date":"2024-10-23T16:08:00","date_gmt":"2024-10-23T19:08:00","guid":{"rendered":"https:\/\/www.erudio.com.br\/blog\/?p=1747"},"modified":"2024-11-02T18:47:58","modified_gmt":"2024-11-02T21:47:58","slug":"como-versionar-uma-api-rest","status":"publish","type":"post","link":"https:\/\/www.erudio.com.br\/blog\/como-versionar-uma-api-rest\/","title":{"rendered":"Como Versionar uma API REST<\/strong>"},"content":{"rendered":"\n

Se voc\u00ea n\u00e3o est\u00e1 muito familiarizado com APIs, pode estar se perguntando… por que toda essa confus\u00e3o em torno do versionamento<\/em><\/em> de API’s?<\/p>\n\n\n\n

Se voc\u00ea j\u00e1 foi impactado por mudan\u00e7as em APIs, provavelmente \u00e9 voc\u00ea quem est\u00e1 preocupado. Se voc\u00ea \u00e9 o respons\u00e1vel por manter uma API, tamb\u00e9m pode estar lidando com perguntas desafiadoras como estas:<\/p>\n\n\n

\n# Esta \u00e9 a vers\u00e3o 2 apenas dos produtos ou de toda a API?\n\/v2\/products\n\n# O que catalisou a mudan\u00e7a entre v1 e v2? Como elas s\u00e3o diferentes?\n\/v1\/products\n\/v2\/products\n<\/pre>\n\n\n\n
Essas perguntas sobre versionamento<\/em><\/em> n\u00e3o s\u00e3o f\u00e1ceis de responder. Nem sempre \u00e9 claro a que a v1 ou v2 se refere. E n\u00e3o devemos simplesmente criar uma segunda vers\u00e3o de um endpoint<\/em> quando a primeira parecer n\u00e3o ser mais suficiente.<\/p>\n\n\n\n
H\u00e1 raz\u00f5es claras pelas quais sua API precisa ter versionamento<\/em><\/em>, e existem estrat\u00e9gias claras para navegar efetivamente pelas mudan\u00e7as na API.<\/p>\n\n\n\n
No entanto, descobri que a maioria dos desenvolvedores – incluindo eu mesmo, at\u00e9 aprender algumas li\u00e7\u00f5es da maneira mais dif\u00edcil – n\u00e3o conhece essas raz\u00f5es e estrat\u00e9gias.<\/p>\n\n\n\n
Este artigo busca destacar essas raz\u00f5es para o versionamento<\/em><\/em> e estrat\u00e9gias para realiz\u00e1-lo. Vamos assumir um contexto de API REST, j\u00e1 que \u00e9 um padr\u00e3o para muitas API’s, e focar no aspecto de versionamento<\/em><\/em>.<\/p>\n\n\n\n\n  \n<\/a>\n\n\n\n
O que \u00e9 Versionamento<\/em>?<\/h3>\n\n\n\n
Devemos come\u00e7ar esclarecendo o que significa o termo “versionamento de API”. Aqui est\u00e1 nossa defini\u00e7\u00e3o:<\/p>\n\n\n\n
\n
O versionamento de API’s \u00e9 a pr\u00e1tica de gerenciar de maneira transparente as mudan\u00e7as na sua API.<\/p>\n<\/blockquote>\n\n\n\n
Versionamento<\/em><\/em> \u00e9 comunica\u00e7\u00e3o eficaz sobre mudan\u00e7as em sua API, para que os consumidores saibam o que esperar dela. Voc\u00ea est\u00e1 fornecendo dados ao p\u00fablico de alguma forma e precisa comunicar quando altera a maneira como esses dados s\u00e3o entregues.<\/p>\n\n\n\n
Isso se resume, na pr\u00e1tica, a gerenciar contratos de dados e mudan\u00e7as disruptivas. O primeiro \u00e9 o bloco de constru\u00e7\u00e3o principal da sua API e o \u00faltimo revela por que o versionamento<\/em><\/em> \u00e9 necess\u00e1rio.<\/p>\n\n\n\n
Contratos de Dados<\/h3>\n\n\n\n
Uma API \u00e9 uma Application Programming Interface<\/em>, e uma interface \u00e9 uma fronteira compartilhada para troca de informa\u00e7\u00f5es. O contrato de dados \u00e9 o cora\u00e7\u00e3o dessa interface.<\/p>\n\n\n\n
<\/p>\n\n\n\n
\n
Um contrato de dados \u00e9 um acordo sobre a estrutura e o conte\u00fado geral dos dados de request e\/ou response.<\/p>\n<\/blockquote>\n\n\n\n
Para ilustrar um contrato de dados, aqui est\u00e1 um corpo de response JSON b\u00e1sico:<\/p>\n\n\n\n
<\/p>\n\n\n\n
{\n  \"data\": [\n    {\n      \"id\": 1,\n      \"name\": \"Produto 1\"\n    },\n    {\n      \"id\": 2,\n      \"name\": \"Produto 2\"\n    }\n  ]\n}\n<\/code><\/pre>\n\n\n\n
Esse \u00e9 um objeto com uma propriedade data<\/code> que \u00e9 uma lista de produtos, cada um com uma propriedade id<\/code> e name<\/code>. Mas a propriedade data<\/code> poderia facilmente ter sido chamada de body<\/code>, e a propriedade id<\/code> em cada produto poderia ser um GUID em vez de um n\u00famero inteiro. Se um \u00fanico produto estivesse sendo retornado, data<\/code> poderia ser um objeto em vez de uma lista.<\/p>\n\n\n\n
Essas mudan\u00e7as aparentemente sutis teriam criado um acordo diferente, um contrato diferente, em rela\u00e7\u00e3o ao “formato” dos dados. O formato dos dados poderia se aplicar a nomes de propriedades, tipos de dados ou at\u00e9 mesmo ao formato esperado (JSON vs. XML).<\/p>\n\n\n\n\n  \n<\/a>\n\n\n\n
Por que o Versionamento<\/em><\/em> \u00e9 Necess\u00e1rio?<\/h3>\n\n\n\n
Com APIs, algo t\u00e3o simples quanto mudar o nome de uma propriedade de productId<\/code> para productID<\/code> pode causar problemas para os consumidores. Isso aconteceu com nossa equipe na semana passada.<\/p>\n\n\n\n
Felizmente, t\u00ednhamos testes para capturar mudan\u00e7as no contrato da API. No entanto, n\u00e3o dever\u00edamos precisar desses testes, pois os respons\u00e1veis pela API deveriam saber que isso seria uma mudan\u00e7a disruptiva.<\/p>\n\n\n\n
Mudan\u00e7as Disruptivas<\/h3>\n\n\n\n
Essa foi uma mudan\u00e7a disruptiva no contrato de dados acordado, porque a altera\u00e7\u00e3o deles nos for\u00e7ou a mudar nossa aplica\u00e7\u00e3o tamb\u00e9m.<\/p>\n\n\n\n
\n
O que constitui uma \u201cmudan\u00e7a disruptiva\u201d em um endpoint de API? <\/em>Qualquer mudan\u00e7a no seu contrato de API que force o consumidor a fazer uma altera\u00e7\u00e3o tamb\u00e9m.<\/p>\n<\/blockquote>\n\n\n\n
As mudan\u00e7as disruptivas geralmente se encaixam nas seguintes categorias:<\/p>\n\n\n\n