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/resource
falharão, mas as chamadas http://example.com/v2/resource
continuarão funcionando.
Qual é a maneira apropriada de indicar falha? Considerei usar um 410 GONE
có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 400
código de status genérico , mas isso também parecia estranho. Existe uma resposta padrão para isso?
Respostas:
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 :
Leitura adicional:
fonte
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".
fonte
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.
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
fonte
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.
fonte