Estabilidade, versionamento e descontinuação da API
Antes de construir a longo prazo sobre a RealityConnect API, entenda quais partes da superfície são estáveis, como as operações experimentais são marcadas, e o que esperar entre atualizações.
Operações experimentais
Seção intitulada “Operações experimentais”Algumas operações na referência da API trazem um marcador de estabilidade experimental. Procure por x-scalar-stability: experimental em uma operação no documento OpenAPI (visível como um selo de estabilidade na referência da API renderizada) para identificá-las. Isso é mantido em sincronia automaticamente com a API, então confira lá em vez de confiar em uma lista fixa aqui.
Operações experimentais são reais e podem ser chamadas (não estão desabilitadas nem são apenas uma prévia), mas seus caminhos, parâmetros, payloads, respostas ou disponibilidade podem mudar sem as mesmas garantias de estabilidade do restante da API. Veja Primeiros passos: Endpoints experimentais para saber como trabalhar com elas.
Quando uma operação experimental se torna estável, isso é anunciado nas notas de versão.
Mudanças disruptivas e não disruptivas
Seção intitulada “Mudanças disruptivas e não disruptivas”| Mudança | Disruptiva? | Por quê |
|---|---|---|
| Novo parâmetro de requisição opcional | Não | As requisições existentes continuam funcionando sem alteração |
| Novo campo de resposta | Não | Clientes existentes que leem campos conhecidos não são afetados; processe as respostas de forma tolerante e ignore campos não reconhecidos |
| Novo valor de enum adicionado a um campo existente | Não | Trate campos de enum como conjuntos abertos e lide com valores não reconhecidos de forma flexível, em vez de comparar exaustivamente cada valor conhecido |
| Campo existente removido ou renomeado | Sim | Quebra qualquer cliente que leia esse campo |
| Tipo ou significado de um campo existente alterado | Sim | Quebra qualquer cliente que dependa da forma anterior |
| Parâmetro obrigatório adicionado a uma operação existente | Sim | Quebra requisições existentes que não o enviam |
| Caminho do endpoint ou método HTTP alterado | Sim | Quebra as requisições existentes por completo |
| Contrato de uma operação experimental muda | Não (intencional) | Operações experimentais são explicitamente isentas do contrato de estabilidade; veja acima |
Política de descontinuação
Seção intitulada “Política de descontinuação”Antes de ser removida, uma operação estável é descontinuada com uma data de encerramento (sunset). A referência da API marca a operação como descontinuada, e sua definição OpenAPI inclui deprecated: true e a data de encerramento em x-sunset (YYYY-MM-DD).
- Uma operação estável descontinuada continua funcionando até sua data de encerramento, e pode ser removida a partir dessa data.
- Não há prazo mínimo de aviso fixo: a data de encerramento de cada descontinuação é o seu aviso.
- Um parâmetro de requisição descontinuado com data de encerramento segue a mesma regra.
- Alguns parâmetros de consulta são renomeados com um alias retrocompatível: o nome antigo continua funcionando junto com o novo.
- Operações experimentais são isentas: podem ser descontinuadas sem data de encerramento, e alteradas ou removidas sem aviso, conforme Operações experimentais.
Próximos passos
Seção intitulada “Próximos passos”- Veja a referência da API para o marcador de estabilidade atual e o esquema de requisição e resposta de cada operação.
- Veja Primeiros passos para o modelo de segurança e como escolher um fluxo OAuth.