Executando uma API, se eu corrigir um cabeçalho de tipo de conteúdo, isso quebrará as coisas para os clientes?

Question

Estamos executando uma API com várias pessoas que a usam. Devido a alguma falta de jeito legado de minha parte, um dos endpoints está retornando o cabeçalho do tipo de conteúdo errado , js quando deveria ser json . A minha pergunta é: se consertarmos isso trocando para retornar o valor correto, o quanto isso poderia atrapalhar as coisas para os clientes existentes? Ou, em outras palavras, você esperaria que muitas bibliotecas-cliente HTTP lançassem erros fatais ao ver tal mudança?

Estamos tentando decidir se essa é uma mudança que podemos seguir em frente e fazer sem suar muito, ou devemos enviar um e-mail com cuidado a todos os usuários e anunciar um período de suspensão de vários anos ... ou algo entre eles .

Provavelmente depende um pouco de que tipos de clientes HTTP diferentes estão em uso, então eu dei uma olhada nos agentes do usuário. Resposta: muitos diferentes! Aqui estão alguns dos principais:

"okhttp / 3.2.0", "python-requests / 2.10.0", "Ruby", "python-requests / 2.7.0", "Mozilla / 5.0", "Java / 1.8.0_91 "," python-requests / 2.4.3 "," okhttp / 3.3.0 "," Lucee "," Dalvik / 2.1.0 "," Google-HTTP-Java-Client / 1.21.0 "," PHP_appname ", "NativeHost", "Java / 1.7.0_67", "Apache-HttpClient / não disponível", "Dalvik / 1.6.0", "Web-sniffer / 1.1.0", "unirest-objc / 1.1"

Várias bibliotecas de idiomas diferentes para dispositivos móveis e servidores. Principalmente não navegadores executando javascript, mas alguns deles também.

A maioria das pessoas parece não perceber que o tipo de conteúdo está errado, mas de vez em quando uma nova solicitação de suporte aparece reclamando sobre esse problema, por isso gostaríamos de solucioná-lo.

    

Answer 1

how badly could it mess things up for our existing customers?

Poderia afundar completamente seus encouraçados se eles tivessem escrito códigos que dependessem do Tipo de Conteúdo estar incorreto.

Eu não esperaria que as bibliotecas lançassem erros, mas espero que em alguns casos as bibliotecas restritas tenham seu comportamento substituído para manipular o tipo MIME incorreto.

Se sua API tiver um valor de versão / revisão em um campo de solicitação em algum lugar, aumente-o e, na nova versão, retorne o tipo correto, mas continue a retornar o tipo incorreto nas versões mais antigas. Se você não tem esse campo de solicitação, agora é um bom momento para adicionar um.

    

Answer 2

Would you expect many different HTTP client libraries to throw fatal errors when seeing such a change?

Não. Cada biblioteca de cliente HTTP com a qual estou familiarizado ignorará o cabeçalho do tipo de conteúdo, a menos que o programador leia especificamente esse cabeçalho e faça algo com ele. Eu posso imaginar uma biblioteca onde o tipo de conteúdo: application / json automaticamente faz com que um json parser seja envolvido, mas eu não sei de nenhum caso em que isso realmente aconteça.

Most people don't seem to notice that the content-type is wrong, but every now and then a new support request pops up complaining about this issue, so we'd like to fix it.

Como eles notaram o cabeçalho incorreto? Pode valer a pena olhar para isso, porque se o cabeçalho incorreto estava realmente causando problemas, eles claramente não estavam apenas ignorando, e eles podem ter problemas se forem corrigidos.

    

Answer 3

É muito difícil dizer sem obter aprovação de todos os seus clientes. Sugiro tomar uma das duas abordagens a seguir para atualizar sua API para v.Next.

1. Estenda a API existente. Adicione uma string de consulta ou alguma outra variável à sua API que signifique usar v.Next. Para todas as solicitações que usam essa variável, use o tipo de conteúdo atualizado.
2. Execute uma instância de preparação ou pré-produção de sua API em paralelo com sua API atual. Deve ser quase idêntico à produção. Mesmo usando o mesmo back-end. Embora este tenha as alterações propostas para v.Next.

Em qualquer cenário, comunique a seus clientes as alterações que você gostaria de fazer e a data / hora de transição de destino. Incentive-os a testar bem antes da data prevista para garantir que não haja interrupção do serviço.

Certifique-se de ter uma página dedicada detalhando as alterações feitas no v.Next. Isso deve ser incluído nas comunicações enviadas aos seus clientes. Se você discutiu alguma correção com clientes existentes, inclua aqueles nesta página.

Por fim, trilhe a linha entre a comunicação excessiva com seus clientes e o envio de spam. Essas notificações podem ser facilmente desconsideradas à medida que surgem prioridades mais imediatas / urgentes.

FWIW, se as coisas estão funcionando, eu não me preocuparia muito com isso. Se, por exemplo, você descobrir que isso causa uma vulnerabilidade de segurança significativa, isso seria um ótimo motivo para promover essa alteração. Caso contrário, eu esperaria por algo mais urgente para incluir essa mudança.

    

Answer 4

Aqui está um exemplo de uma biblioteca (bem, comando único) que isso quebraria:

powershell cmdlet Invoke-RestMethod age de maneira diferente com o JSON. Se o resultado da solicitação for JSON, XML ou ATOM / RSS (e acho que é baseado no cabeçalho), ele será analisado / desserializado e retornará objetos nativos, caso contrário, retornará os dados brutos.

Assim, o código existente seria escrito para lidar com uma string (talvez passando para ConvertFrom-Json ), e de repente começar a falhar.

    

Answer 5

Eu notei duas conseqüências:

1. Algumas bibliotecas cliente não processam a resposta corretamente. Por exemplo, a resposta retorna uma string em vez de json ou uma matriz.
2. A compactação nem sempre é aplicada.