# Versionamento e estabilidade

Como a API é versionada, quais mudanças podem chegar sem uma nova versão maior e como se fixar na v1.

O PDF Blocks versiona a API para que você possa adotar melhorias sem medo de
quebras inesperadas. As regras abaixo dizem exatamente quais mudanças é seguro
receber automaticamente e como qualquer mudança incompatível chegaria até você.

## Versionamento semântico

A API segue o [Versionamento Semântico 2.0.0](https://semver.org). Dado um
número de versão `X.Y.Z`:

| Parte | Nome     | Significado                                   |
| ----- | -------- | --------------------------------------------- |
| `X`   | Maior    | Mudanças incompatíveis com versões anteriores. |
| `Y`   | Menor    | Adições de recursos retrocompatíveis.          |
| `Z`   | Correção | Correções de bugs retrocompatíveis.            |

A versão atual da especificação é `1.18.0`. Você sempre pode ler a versão
vigente no campo `info.version` da
[especificação OpenAPI](/docs/api/openapi-specification).

## A versão maior `v1` no caminho

A versão **maior** fica fixada no caminho da URL: toda ação vive sob `/v1/`,
como em `https://api.pdfblocks.com/v1/add_text_watermark`. As versões menores e
de correção são publicadas no mesmo lugar, sob `/v1/`. Você as recebe
automaticamente e nunca muda suas URLs para obtê-las. Como as mudanças
incompatíveis só são publicadas sob uma nova versão maior (um novo segmento de
caminho), permanecer em `/v1/` significa permanecer em um contrato estável.

## O que conta como retrocompatível

Dentro da `v1`, fazemos mudanças aditivas sem uma nova versão maior. Trate tudo
o que segue como algo que pode aparecer a qualquer momento e escreva clientes
que tolerem isso:

- **Novos parâmetros opcionais** em uma ação existente.
- **Novos valores aceitos** para um parâmetro existente: uma enumeração
  ampliada.
- **Aliases de parâmetros**: um novo nome para um campo existente, com o nome
  antigo ainda aceito.
- **Respostas mais ricas**: novos campos em um corpo de resposta ou novos
  cabeçalhos de resposta.
- **Novas ações e novos endpoints.**

Nenhuma dessas mudanças exige que você fixe uma versão menor nem que altere seu
código. Para se manter compatível, ignore os campos de resposta que não
reconhecer, em vez de falhar por causa deles, e não presuma um conjunto fixo e
exaustivo de valores de enumeração.

## Como as mudanças incompatíveis são publicadas

Uma mudança incompatível (remover ou renomear um parâmetro obrigatório, alterar
uma resposta de forma incompatível ou mudar um comportamento estabelecido) só
seria publicada como uma **nova versão maior sob um novo caminho**, como `/v2/`.
Suas chamadas a `/v1/` continuam funcionando sem alteração, e você migra no seu
próprio ritmo. Não fazemos mudanças incompatíveis no mesmo lugar sob `/v1/`.

## Fixe-se em uma versão maior

Fixe sua integração na versão maior `v1` mantendo `/v1/` nas URLs das suas
requisições. Isso é tudo o que você precisa fixar: você recebe automaticamente
as melhorias menores e de correção retrocompatíveis, enquanto as mudanças
incompatíveis ficam fora do seu caminho até que você opte por adotar uma versão
maior futura.

Acompanhe o que mudou em cada versão no
[Registro de alterações](/docs/api/changelog).