standard services restful practices best actions rest versioning

services - standard api restful



Control de versiones RESTful services? (4)

Creo que no deberías hacer esto en primer lugar, pero probablemente sea demasiado tarde.

Los URI también deben ser estáticos, de modo que cuando el recurso cambie o la implementación del servicio cambie, el enlace se mantendrá igual. Esto permite marcar. También es importante que la relación entre los recursos codificados en los URI permanezca independiente de la forma en que se representan las relaciones donde se almacenan.

Del artículo RESTful Web services: Lo básico .

Tengo un servicio web RESTful implementado en http://example.com/v1/SomeResource . Un día, una nueva versión de protocolo ( que no es compatible con versiones anteriores ) se implementa en http://example.com/v2/SomeResource . Desde el punto de vista del cliente, esta actualización podría ocurrir en cualquier momento entre dos solicitudes HTTP.

¿Cómo indica el servidor al cliente que ya no admite llamadas v1 y se espera que el cliente se actualice a v2? ¿Hay un código de respuesta apropiado que pueda usar?

Me gustaría proporcionarle al cliente la siguiente información:

  1. Se ha producido una actualización incompatible. No hay forma de que el cliente use el nuevo servicio porque el protocolo podría ser totalmente diferente.
  2. La URL del nuevo software de cliente.
  3. Un mensaje que explica a los usuarios que deben actualizar.

En cambio, recomendaría el uso del 301 (301 Movido permanentemente). Lea por qué .

Espero que ayude, Bruno Figueiredo

Mejores prácticas:

Probablemente sea mejor mantener el control de versiones de la URL y hacer que los nuevos recursos sean compatibles con versiones anteriores.

Compatible con versiones anteriores:

Si debe mantener la v1 en la URL y está creando URL v2, debe decidir si desea admitir ambos formatos o hacer obsoleta la antigua v1. Si decide dejar obsoleta la antigua v1, le recomendaría devolver 303 o 401 para cualquier persona que solicite una URL v1.

Hacer viejas URLs obsoletas:

Yo recomendaría usar 303 Ver Otro. O si no hay una redirección asociada, entonces use 410 Gone.

Fuente

303 Ver otros

La respuesta a la solicitud se puede encontrar bajo un URI diferente y DEBERÍA recuperarse utilizando un método GET en ese recurso. Este método existe principalmente para permitir que la salida de una secuencia de comandos activada POST redirija el agente de usuario a un recurso seleccionado. El nuevo URI no es una referencia sustituta para el recurso solicitado originalmente. La respuesta 303 NO DEBE almacenarse en caché, pero la respuesta a la segunda solicitud (redireccionada) puede almacenarse en caché.

Los diferentes URI DEBERÍAN darse por el campo Ubicación en la respuesta. A menos que el método de solicitud fuera HEAD, la entidad de la respuesta DEBERÍA contener una breve nota de hipertexto con un hipervínculo al nuevo URI (s).

Nota: Muchos agentes de usuario anteriores a HTTP / 1.1 no entienden el estado 303. Cuando la interoperabilidad con dichos clientes es una preocupación, el código de estado 302 puede utilizarse en su lugar, ya que la mayoría de los agentes de usuario reaccionan a una respuesta 302 como se describe aquí para 303.

Documenta todo:

Lo principal de lo que debe preocuparse es lo que sea que elija devolver, solo documéntelo en su documentación. Puede decidir cómo quiere que su servicio funcione, otros que quieran consumirlo seguirán la documentación.