Adicionando a um conjunto finito de opções; uma alteração de quebra de API?

9

Adote um ponto de extremidade da API HTTP que cospe o seguinte modelo de resposta:

{
    "type": "Dog",
    "name": "Jessi",
    ...
}

O typecampo foi descrito na documentação como sendo um dos Dog, Catou Fish.

A adição de uma nova opção, por exemplo Rat, seria considerada uma alteração de API quebrada?

A adição de uma opção a uma lista finita (na qual um desenvolvedor pode ativar) é considerada uma extensão ou uma modificação de uma API?

rest api api-design json Dave New
fonte

Respostas:

10

Se a documentação descreveu esse campo como sendo um cão, um gato ou um peixe, sim, adicionar outro tipo altera a interface de uma maneira incompatível com versões anteriores. É perfeitamente concebível que um consumidor de sua API tenha escrito um código específico para lidar com cães e gatos de maneira diferente do que com peixes. Dado um tipo desconhecido, esse consumidor não saberia o que fazer com sua resposta. Mas isso depende muito do que esses tipos de espaço reservado "Gato" e "Peixe" representam no seu domínio de problema real ...

Se as alterações na lista de tipos possíveis forem frequentes, ou se a lista não for finita, é recomendável documentar isso como tal. Dependendo dos seus casos de uso, pode ser bom expor uma lista de todos os tipos possíveis como um ponto de extremidade em sua API - assim fica claro que você pode adicionar ou remover tipos sem precisar atualizar a versão da API. No entanto, quanto mais dinâmicos forem os seus tipos, mais difícil será para os consumidores de API fazer algo específico ao tipo. A extensibilidade ou facilidade de uso é mais importante depende dos casos de uso e do domínio do problema.

amon
fonte
Resposta fantástica - obrigado. E se a documentação detalhasse as opções em alguma tabela intitulada "a tabela a seguir descreve os animais atualmente suportados pela API". Isso não indica que as opções possam ser expandidas?
Dave New
11
@davenewza Essa é provavelmente uma boa ideia, mas eu seria mais explícito. Não basta indicar o que você quer dizer - diga diretamente! Eu tentaria definir expectativas claras e oferecer uma garantia de estabilidade nos documentos para esse endpoint, algo como: “A tabela a seguir lista os animais atualmente suportados, embora possamos adicionar ou remover animais suportados no futuro. Quando isso acontecer, atualizaremos o número da versão secundária da API. ”
amon
Especificação executável >>> especificação documentada >>> especificação não documentada.
VoiceOfUnreason
0

Seria interrompido apenas se "Rat" pudesse ser retornado de operações existentes.

Se as operações existentes não puderem retornar "Rato", a adição desta nova opção não terá efeito.

Jon Raynor
fonte