Qual é o código de status HTTP correto para: "Esta versão desta API foi descontinuada"?

Eu tenho uma API RESTful. Existem três versões: v1, v2 e v3. Estou prestes a publicar a v4 e decidimos interromper a v1, o que significa que todas as solicitações http://example.com/v1/resourcefalharão, mas as chamadas http://example.com/v2/resourcecontinuarão funcionando.

Qual é a maneira apropriada de indicar falha? Considerei usar um 410 GONEcódigo de status, mas isso indica que o recurso não está mais disponível. O recurso provavelmente ainda está disponível, mas deve ser solicitado de uma maneira diferente.

Também considerei um 400código de status genérico , mas isso também parecia estranho. Existe uma resposta padrão para isso?

Não parece haver um padrão.

A resposta StackOverflow se inclina para 410 GONE, mas acho que 301 MOVIDO PERMANENTEMENTE é mais apropriado.

Para fazer a escolha correta, precisamos analisar seu caso específico. Se seu objetivo é que todas as chamadas feitas para a API v1 falhem sem tomar nenhuma ação adicional, o 410 GONE trabalha para isso. Se você deseja alguma continuidade, como redirecionar o cliente para uma versão mais recente da sua API, onde a chamada pode ser bem-sucedida, o 3XX funciona, mas qual você escolhe? Acho que se você está tentando desligar a API v1, o 301 MOVED PERMANENTLY ajuda a indicar que é melhor que 303 VEJA OUTROS, porque o 301 sugere que todas as solicitações futuras sejam feitas ao novo URL, enquanto o 303 não indica se essa situação é ou não permanente.

Eu recomendaria projetar a API de forma que cada versão permaneça compatível com versões anteriores, para que o 301 MOVED PERMANENTLY mantenha transparentemente sua API ativa e atualizada sempre que você adicionar novos pontos de extremidade para novas versões da API. Eu acho que é o que você está tentando fazer de qualquer maneira.

Códigos de status HTTP

O código de status HTTP 302 era originalmente muito amplo e, portanto, tornou-se implementado / usado incorretamente; portanto, 303 e 307 foram feitos para distinguir entre o caso de uso duplo do 302. Algumas APIs usam 303 para outros fins.

301 MOVIDO PERMANENTEMENTE - O código de status 301 (Movido permanentemente) indica que o recurso de destino recebeu um novo URI permanente e quaisquer referências futuras a esse recurso devem usar um dos URIs incluídos.

302 ENCONTRADO - O código de status 302 (encontrado) indica que o recurso de destino reside temporariamente em um URI diferente. Como o redirecionamento pode ser alterado ocasionalmente, o cliente deve continuar usando o URI de solicitação efetivo para solicitações futuras.

303 VER OUTROS - Uma resposta 303 a uma solicitação GET indica que o servidor de origem não possui uma representação do recurso de destino que pode ser transferido pelo servidor por HTTP. No entanto, o valor do campo Local refere-se a um recurso que é descritivo do recurso de destino, de modo que fazer uma solicitação de recuperação nesse outro recurso pode resultar em uma representação que é útil para os destinatários sem implicar que ele representa o recurso de destino original.

410 GONE - O código de status 410 (Gone) indica que o acesso ao recurso de destino não está mais disponível no servidor de origem e que essa condição provavelmente será permanente. Se o servidor de origem não souber ou não tiver a capacidade de determinar se a condição é permanente ou não, o código de status 404 (Não encontrado) deve ser usado.

Como as APIs existentes lidam com isso?

Talvez você possa tirar uma página da API do YouTube do Google :

Quando uma solicitação de API falha, o YouTube retorna um código de resposta HTTP 4xx ou 5xx que identifica genericamente a falha, bem como uma resposta XML que fornece informações mais específicas sobre os erros que causaram a falha. Para cada erro, a resposta XML inclui um elemento de domínio, elemento de código e possivelmente um elemento de localização.

• A API do BigCommerce usa 302 FOUND.
• As Diretrizes da API REST da Atlassian sugerem 301 MOVIDO PERMANENTEMENTE, juntamente com um subcódigo que descreve o erro em detalhes. Isso é semelhante à abordagem da API do YouTube.

Leitura adicional:

• Como as APIs REST são versionadas?
• Design da API da Netflix: quando mudar a tendência

Os redirecionamentos são ótimos para os recursos que foram movidos. Em vez de um redirecionamento permanente 301 (o que indicaria uma renomeação sem alterações de API), eu usaria um redirecionamento 303 "See Other".

Ainda precisa dar suporte ao legado sem redirecionamentos? Mesmo se você ainda o estiver apoiando e, no fundo, ele ainda estiver implementado, o 501 parece estar de mãos dadas com a sua situação. Os conhecedores ainda poderiam usá-lo, enquanto os randoms veriam o 501 para a v1.

10.5.2 501 Não implementado

O servidor não suporta a funcionalidade necessária para atender à solicitação. Essa é a resposta apropriada quando o servidor não reconhece o método de solicitação e não é capaz de suportá-lo para nenhum recurso.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Eu usaria o 503 com uma mensagem de que o serviço não está disponível e indicaria o uso da versão mais recente. Essa mensagem pode ser retornada para 50% das chamadas e, com o tempo, aumentar gradualmente para 100%.

Para uma migração transparente, eu usaria 308 - redirecionamento permanente, pois esse método não modifica o verbo (POST será POST) diferente de 301.