# 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).