Estabilidade e versionamento 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 |
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.