Tipos de mudanças
Veja o que consideramos como mudanças disruptivas.
Introdução
O objetivo deste documento é detalhar quando uma ou mais mudanças nas nossas APIs serão consideradas:
- disruptivas (breaking changes), o que exigirá a criação de uma nova versão maior (major); ou
- não disruptivas (non breaking changes), o que exigirá a criação de uma nova versão menor (minor) ou de correção (patch).
Política de versionamento
Conheça nossa Política de versionamento.
Mudanças em APIs REST podem ocorrer:
- no contrato da API (Open API 3.0), tendo efeitos mais visíveis aos consumidores e, portanto, sendo mais fácil de se mapear os seus impactos; ou
- em suas regras de negócio/implementação, precisando de uma análise mais complexa de quando uma mudança traz impactos aos atuais consumidores das APIs.
Por se basear no protocolo HTTP, uma API REST é composta de vários elementos que podem ser alterados causando impactos aos seus consumidores. Veja a seguir:
Request
verbo
;schema
;recurso
;pathParams
;queryParams
;headers
; ebody
.
Estrutura padrão:
<VERBO> <schema>://<host>:<porta>/<uri>/<pathParam>?<queryParam>=ipsum#\<seção>
<header>: ipsum loren
<body>
Response:
status code
;headers
; ebody
.
Estrutura padrão:
<HTTP Status>
<Header>: ipsum loren
<body>
Callbacks (webhooks)
pathParams
;queryParams
;headers
;body
;próprio uso do webhook
.
Estrutura padrão:
<VERBO> <schema>://<callbackUri>/<pathParam>?<queryParam>=ipsum
<header>: ipsum loren
<body>
Mudanças disruptivas (breaking changes)
1. Remover um recurso
Exemplo: a API originalmente define três recursos e na nova versão exclui o recurso 2.
Versão 1 | Versão 2 |
---|---|
/api/v1/recurso1 | /api/v2/recurso1 |
/api/v1/recurso2 | |
/api/v1/recurso3 | /api/v2/recurso3 |
2. Remover um verbo de um recurso (operação)
Exemplo: a API originalmente define um recurso com três operações e na nova versão uma das operações foi removida.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1 | GET /api/v2/recurso1 |
GET /api/v1/recurso1/{id} | GET /api/v2/recurso1/{id} |
PUT /api/v1/recurso1/{id} | PUT /api/v2/recurso1/{id} |
3. Alterar o verbo de um recurso (operação)
Exemplo: a API originalmente define um recurso com o verbo PUT
e na nova versão ele é alterado para PATCH
.
Versão 1 | Versão 2 |
---|---|
PUT /api/v1/recurso1/{id} | PATCH /api/v2/recurso1/{id} |
4. Remover um path
Exemplo: a API originalmente define um path para acessar apenas os dados do subrecurso2 com facilidade. A nova versão remove este path.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1/{id} | GET /api/v2/recurso1/{id} |
GET /api/v1/recurso1/{id}/subrecurso1 | GET /api/v2/recurso1/{id}/subrecurso1 |
GET /api/v1/recurso1/{id}/subrecurso2 |
5. Remover um parâmetro do request (pathParam e/ou queryParam)
Exemplo 1: a API originalmente define um pathParam que identifica o recurso. A nova versão não possui mais este parâmetro, não sendo mais possível identificar o recurso.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1/{id}/subrecurso1 | GET /api/v2/recurso1/subrecurso1 |
Exemplo 2: a API originalmente define como queryParam um filtro. A nova versão não possui mais este filtro.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1?filter=lorem | GET /api/v2/recurso1 |
6. Renomear um parâmetro (queryParam e/ou body)
Exemplo 1: a API originalmente define como queryParam um filtro. A nova versão renomeia este filtro.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1?filter=lorem | GET /api/v1/recurso1?renamedfilter=ipsum |
7. Adicionar um parâmetro obrigatório no request (pathParam, queryParam e/ou body)
Exemplo 1: a API originalmente define um recurso. A nova versão acrescenta um pathParam.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1 | GET /api/v2/recurso1/{id} |
Exemplo 2: a API originalmente define um recurso. A nova versão acrescenta um queryParam.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1 | GET /api/v2/recurso1?filter=lorem |
8. Alterar local onde um parâmetro é recebido
Exemplo 1: A API originalmente recebe um parâmetro no body e, na nova versão, é esperado como um query param.
Versão 1 | Versão 2 |
---|---|
POST /api/v1/recurso1 Corpo: { "parametro": "valor" } | POST /api/v2/recurso1?parametro=valor |
Exemplo 2: A API originalmente recebe um query param e, na nova versão, é esperado como um path param.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1?id=123 | GET /api/v2/recurso1/123 |
9. Alterar um parâmetro do tipo enum (adicionar ou remover valores)
Exemplo 1: Adicionar ou remover valores das opções possíveis entre as versões da API.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1?status=ativo | GET /api/v2/recurso1?status=novo |
Exemplo 2:
Versão 1 | Versão 2 |
---|---|
PUT /api/v1/recurso1/123 Corpo: { "tipo": "regular" } | PUT /api/v2/recurso1/123 Corpo: { "tipo": "premium" } |
10. Remover o suporte a um tipo de conteúdo (content-type) previamente aceito no request
Exemplo: A API originalmente dava suporte a um tipo de conteúdo no request e, na versão nova, deixa de dar.
Versão 1 | Versão 2 |
---|---|
POST /api/v1/recurso1 Content-Type: application/json Corpo: { "parametro": "valor" } | POST /api/v2/recurso1 Content-Type: application/xml Corpo: <parametro>valor</parametro> |
11. Remover o suporte a um tipo de conteúdo (content-type) previamente aceito no response
Exemplo: A API originalmente dava suporte a um tipo de conteúdo no response e, na nova versão, deixa de dar.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1/123 Accept: application/json | GET /api/v2/recurso1/123 Accept: application/xml |
12. Adicionar um header obrigatório no request
Exemplo: A API originalmente não continha um header e, na nova versão, um novo header obrigatório é adicionado ao request.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1 | GET /api/v2/recurso1 Obrigatorio: true |
13. Remover um header do response
Exemplo: A API originalmente continha um header no response e, na nova versão, o header foi removido.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1 | GET /api/v2/recurso1 |
14. Alterar a estrutura do body (request, response e/ou webhook)
Exemplo 1: A API originalmente tinha uma estrutura de request e, na nova versão, essa estrutura foi alterada (o que pode incluir alterações na estrutura JSON, tipos de dados ou nomes de campos).
Versão 1 | Versão 2 |
---|---|
POST /api/v1/recurso1 Corpo: { "nome": "John", "idade": 25 } | POST /api/v2/recurso1 Corpo: { "primeiroNome": "John", "idadeAtual": 25 } |
Exemplo 2: A API originalmente tinha uma estrutura de response e, na nova versão, essa estrutura foi alterada (o que pode incluir alterações na estrutura JSON, tipos de dados ou nomes de campos).
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1/123 | GET /api/v2/recurso1/123 Corpo: { "id": 123, "informacoes": { "detalhes": "Detalhes aqui" } } |
Exemplo 3: A API originalmente tinha uma estrutura de webhook e, na nova versão, essa estrutura foi alterada (o que pode incluir alterações na estrutura JSON, tipos de dados ou nomes de campos).
Versão 1 | Versão 2 |
---|---|
Webhook: /webhook/v1 Corpo: { "evento": "novo_dado" } | Webhook: /webhook/v2 Corpo: { "tipoEvento": "novo_dado" } |
15. Alterar o tipo de um parâmetro (pathParam, queryParam, header e/ou body)
Exemplo 1: A API originalmente considerava determinado parâmetro como string e, na nova versão, o tipo desse parâmetro foi modificado para inteiro.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1/idade/25 | GET /api/v2/recurso1/idade/25 |
Exemplo 2: A API originalmente considerava determinado parâmetro como string e, na nova versão, o tipo desse parâmetro foi modificado para booleano.
Versão 1 | Versão 2 |
---|---|
PUT /api/v1/recurso1/123 Corpo: { "status": "ativo" } | PUT /api/v2/recurso1/123 Corpo: { "status": true } |
Exemplo 3: A API originalmente considerava determinado parâmetro como string e, na nova versão, o tipo desse parâmetro foi modificado para data.
Versão 1 | Versão 2 |
---|---|
POST /api/v1/recurso1 Corpo: { "dataNascimento": "1990-01-01" } | POST /api/v2/recurso1 Corpo: { "dataNascimento": 631152000000 } |
16. Alterar o formato de um parâmetro (pathParam, queryParam, header e/ou body)
Exemplo 1: A API originalmente utilizava um pathParam
e, na nova versão, passou autilizar um queryParam
.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1/data/2022-01-01 | GET /api/v2/recurso1?data=01-01-2022 |
Exemplo 2: A API originalmente utilizava um parâmetro no body e, na nova versão, passou autilizar no header.
Versão 1 | Versão 2 |
---|---|
PUT /api/v1/recurso1/123 Corpo: { "status": "ativo" } | PUT /api/v2/recurso1/123 Cabeçalho: { "status": "ativo" } |
Exemplo 3: A API originalmente utilizava um parâmetro com determinado formato e, na nova versão, passou a utilizar outro formato.
Versão 1 | Versão 2 |
---|---|
POST /api/v1/recurso1 Corpo: { "dataNascimento": "1990-01-01" } | POST /api/v2/recurso1 Corpo: { "dataNascimento": "01-01-1990" } |
17. Aumentar as restrições de um parâmetro no request (pathParam, queryParam, header e/ou body)
Exemplo: A API originalmente utilizava um parâmetro opcional e, na nova versão, essas restrições foram aumentadas tornando-o obrigatório.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1 | GET /api/v2/recurso1/{id} |
GET /api/v1/recurso1 | GET /api/v2/recurso1?filter=lorem |
GET /api/v1/recurso1 | GET /api/v2/recurso1/{id}/detalhes |
18. Diminuir as restrições de um parâmetro no response (body)
Exemplo: A API originalmente utilizava um parâmetro obrigatório e, na nova versão, essas restrições foram diminuídas tornando-o opcional.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1/123 | GET /api/v2/recurso1/123 Corpo: { "id": 123, "informacoes": { "detalhes": "Detalhes aqui" } } |
19. Alterar o valor padrão de um parâmetro opcional
Exemplo: A API originalmente utilizava determinado valor padrão para um parâmetro opcional e, na nova versão, esse valor foi alterado.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1?limite=10 | GET /api/v2/recurso1?limite=20 |
20. Alterar a forma de representar arrays nos parâmetros (queryParam)
Exemplo: A API originalmente representava arrays de uma forma e, na nova versão, essa representação foi alterada.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1?itens=1&itens=2&itens=3 | GET /api/v2/recurso1?itens\[]=1&itens\[]=2&itens\[]=3 |
21. Adicionar um novo código HTTP de response
Exemplo: A API originalmente não retornava um HTTP Status Code
e, na nova versão, passou a retornar.
Versão 1 | Versão 2 |
---|---|
POST /api/v1/recurso1 | 201 Created POST /api/v2/recurso1 |
22. Remover um código HTTP de response
Exemplo: A API originalmente retornava um HTTP Status Code
e, na nova versão, deixou de retornar.
Versão 1 | Versão 2 |
---|---|
201 Created GET /api/v1/recurso1/123 | GET /api/v2/recurso1/123 |
23. Modificar o código HTTP de um response existente
Exemplo: A API originalmente retornava um HTTP Status Code
e, na nova versão, ele foi alterado.
Versão 1 | Versão 2 |
---|---|
GET /api/v1/recurso1/123 | 404 Not Found GET /api/v2/recurso1/123 |
24. Adicionar/remover o uso de callbacks (webhooks) assíncronos
Exemplo: A API originalmente retornava uma resposta assíncrona e, na nova versão, deixou de retornar.
Versão 1 | Versão 2 |
---|---|
Webhook: /webhook/v1 Corpo: { "evento": "novo_dado" } | Webhook: /webhook/v2 Removido o suporte a webhooks assíncronos |
Mudanças não disruptivas (non breaking changes)
Quaisquer mudanças que não se enquadrem na lista de mudanças disruptivas serão consideradas não disruptivas.
Updated 9 months ago