Documentação
DocumentaçãoAPIChangelogSuporteFAQs

Tipos de mudanças

Veja o que consideramos como mudanças disruptivas.

Suggest Edits

Introdução

O objetivo deste documento é detalhar quando uma ou mais mudanças nas nossas APIs serão consideradas:

  1. disruptivas (breaking changes), o que exigirá a criação de uma nova versão maior (major); ou
  2. 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:

  1. 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
  2. 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; e
  • body.

Estrutura padrão:

<VERBO> <schema>://<host>:<porta>/<uri>/<pathParam>?<queryParam>=ipsum#\<seção>
<header>: ipsum loren

<body>

Response:

  • status code;
  • headers; e
  • body.

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 1Versã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 1Versão 2
GET /api/v1/recurso1GET /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 1Versã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 1Versão 2
GET /api/v1/recurso1/{id}GET /api/v2/recurso1/{id}
GET /api/v1/recurso1/{id}/subrecurso1GET /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 1Versão 2
GET /api/v1/recurso1/{id}/subrecurso1GET /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 1Versão 2
GET /api/v1/recurso1?filter=loremGET /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 1Versão 2
GET /api/v1/recurso1?filter=loremGET /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 1Versão 2
GET /api/v1/recurso1GET /api/v2/recurso1/{id}

Exemplo 2: a API originalmente define um recurso. A nova versão acrescenta um queryParam.

Versão 1Versão 2
GET /api/v1/recurso1GET /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 1Versã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 1Versão 2
GET /api/v1/recurso1?id=123GET /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 1Versão 2
GET /api/v1/recurso1?status=ativoGET /api/v2/recurso1?status=novo

Exemplo 2:

Versão 1Versã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 1Versã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 1Versã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 1Versão 2
GET /api/v1/recurso1GET /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 1Versão 2
GET /api/v1/recurso1GET /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 1Versã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 1Versão 2
GET /api/v1/recurso1/123GET /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 1Versã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 1Versão 2
GET /api/v1/recurso1/idade/25GET /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 1Versã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 1Versã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 1Versão 2
GET /api/v1/recurso1/data/2022-01-01GET /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 1Versã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 1Versã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 1Versão 2
GET /api/v1/recurso1GET /api/v2/recurso1/{id}
GET /api/v1/recurso1GET /api/v2/recurso1?filter=lorem
GET /api/v1/recurso1GET /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 1Versão 2
GET /api/v1/recurso1/123GET /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 1Versão 2
GET /api/v1/recurso1?limite=10GET /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 1Versão 2
GET /api/v1/recurso1?itens=1&itens=2&itens=3GET /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 1Versão 2
POST /api/v1/recurso1201 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 1Versã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 1Versão 2
GET /api/v1/recurso1/123404 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 1Versã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 10 months ago