Tengo una API RESTful. Hay 3 versiones de la misma: v1, v2 y v3. Estoy a punto de publicar la v4, y hemos decidido suspender la v1, lo que significa que todas las solicitudes http://example.com/v1/resourcefallarán, pero las llamadas a http://example.com/v2/resourcecontinuarán funcionando.
¿Cuál es la forma apropiada de indicar el fracaso? Pensé en usar un 410 GONEcódigo de estado, pero eso indica que el recurso ya no está disponible. Sin embargo, es probable que el recurso todavía esté disponible, solo que debe solicitarse de manera diferente.
También consideré un 400código de estado genérico , pero también me pareció extraño. ¿Hay una respuesta estándar para esto?
Respuestas:
No parece haber un estándar.
La respuesta de StackOverflow se inclina hacia 410 GONE, pero creo que 301 MOVIDO PERMANENTEMENTE es más apropiado.
Para tomar la decisión correcta, debemos analizar su caso específico. Si su objetivo es hacer que todas las llamadas realizadas a API v1 fallen sin tomar ninguna otra medida, 410 GONE funciona para eso. Si desea algo de continuidad, como redirigir al cliente a una versión más nueva de su API donde su llamada puede tener éxito, 3XX funciona, pero ¿cuál elige? Creo que si está intentando cerrar API v1, 301 MOVIDO PERMANENTEMENTE ayuda a indicar que es mejor que 303 VER OTRO porque 301 sugiere que todas las solicitudes futuras deben hacerse a la nueva url mientras que 303 no indica si esta situación es o no permanente.
Recomendaría diseñar la API de tal manera que cada versión siga siendo compatible con versiones anteriores, de modo que 301 MOVIDO PERMANENTEMENTE mantenga su API viva y actualizada de manera transparente cada vez que agregue nuevos puntos finales para nuevas versiones de API. Creo que eso es lo que estás tratando de hacer de todos modos.
Códigos de estado HTTP
El código de estado HTTP 302 era originalmente demasiado amplio y, por lo tanto, se implementó / usó incorrectamente, por lo que 303 y 307 se hicieron para distinguir entre el caso de uso dual de 302. Algunas API usan 303 para otros fines.
301 MOVIDO PERMANENTEMENTE - El código de estado 301 (Movido permanentemente) indica que al recurso objetivo se le ha asignado un nuevo URI permanente y cualquier referencia futura a este recurso debería usar uno de los URI adjuntos.
302 ENCONTRADO : el código de estado 302 (encontrado) indica que el recurso de destino reside temporalmente bajo un URI diferente. Debido a que la redirección puede ser alterada ocasionalmente, el cliente debe continuar usando el URI de solicitud efectivo para futuras solicitudes.
303 VER OTRO : una respuesta 303 a una solicitud GET indica que el servidor de origen no tiene una representación del recurso de destino que el servidor puede transferir a través de HTTP. Sin embargo, el valor del campo Ubicación se refiere a un recurso que es descriptivo del recurso de destino, de modo que realizar una solicitud de recuperación en ese otro recurso podría dar como resultado una representación útil para los destinatarios sin implicar que representa el recurso de destino original.
410 GONE : el código de estado 410 (Gone) indica que el acceso al recurso de destino ya no está disponible en el servidor de origen y que es probable que esta condición sea permanente. Si el servidor de origen no sabe, o no tiene facilidad para determinar, si la condición es permanente o no, debe utilizarse el código de estado 404 (No encontrado).
¿Cómo manejan esto las API existentes?
Tal vez pueda tomar una página de la API de Youtube de Google :
Otras lecturas:
fuente
Los redireccionamientos son excelentes para los recursos que se han movido. En lugar de una redirección permanente 301 (que indicaría un cambio de nombre sin cambios de API), usaría una redirección 303 "Ver otro".
fuente
¿Todavía necesita soportar el legado sin redireccionamientos? Incluso si todavía lo está apoyando y en el fondo todavía está implementado, el 501 parece bastante de la mano de su situación. Aquellos que lo saben aún podrían usarlo, mientras que los randoms verían el 501 para v1.
http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
fuente
Usaría 503 con un mensaje de que el servicio no está disponible e indicaría que use la versión más nueva. Este mensaje puede devolverse para el 50% de las llamadas y, con el tiempo, aumentar gradualmente al 100%.
Para una migración transparente, usaría 308 - Redirección permanente, ya que este método no modifica el verbo (POST será POST) a diferencia de 301.
fuente