Versiones de recurso REST fácil en implementaciones basadas en JAX-RS?

Question

La mejor práctica para el control de versiones de recurso REST es colocar la información de la versión en los encabezados Accept/Content-Type de la solicitud HTTP que deja el URI intacto.

Aquí está la muestra/respuesta a REST API para recuperar información del sistema: la atención

==> 
GET /api/system-info HTTP/1.1 
Accept: application/vnd.COMPANY.systeminfo-v1+json 

<== 
HTTP/1.1 200 OK 
Content-Type: application/vnd.COMPANY.systeminfo-v1+json 
{ 
    “session-count”: 19 
} 

de pago que se especifica en la versión tipo MIME.

Aquí es otra petición/respuesta para la versión 2:

==> 
GET /api/system-info HTTP/1.1 
Accept: application/vnd.COMPANY.systeminfo-v2+json 

<== 
HTTP/1.1 200 OK 
Content-Type: application/vnd.COMPANY.systeminfo-v2+json 
{ 
    “uptime”: 234564300, 
    “session-count”: 19 
} 

Ver http://barelyenough.org/blog/tag/rest-versioning/ para más explicación y ejemplos.

¿Es posible implementar este enfoque fácilmente en implementaciones basadas en Java JAX-RS, como Jersey o Apache CXF?

El objetivo es tener varias clases @Resource con el mismo valor de @Path, pero sirviendo la solicitud en función de la versión real especificada en el tipo MIME?

He investigado JAX-RS en general y Jersey in particlaur y no encontré soporte para eso. Jersey no da la oportunidad de registrar dos recursos con el mismo camino. La sustitución de la clase WebApplicationImpl debe implementarse para admitir eso.

¿Puede sugerir algo?

NOTA: Se requiere que las versiones múltiples del mismo recurso estén disponibles simultáneamente. Las nuevas versiones pueden introducir cambios incompatibles.

Answer 1

JAX-RS se envía a métodos anotados con @Produces a través del encabezado Accept. Por lo tanto, si desea que JAX-RS realice su despacho, deberá aprovechar este mecanismo. Sin ningún trabajo adicional, tendría que crear un método (y Proveedor) para cada tipo de medio que desee.

No hay nada que te impida tener varios métodos basados ​​en el tipo de medio que todos llaman un método común para hacer ese trabajo, pero tendrías que actualizarlo y agregar código cada vez que agregaras un nuevo tipo de medio.

Una idea es agregar un filtro que "normalice" el encabezado Aceptar específicamente para el envío. Es decir, tal vez, tomando su:

Accept: application/vnd.COMPANY.systeminfo-v1+json 

y convertir que a, simplemente:

Accept: application/vnd.COMPANY.systeminfo+json 

Al mismo tiempo, extraer la información de versión para su uso posterior (tal vez en la solicitud, o alguna otro mecanismo ad hoc).

Luego, JAX-RS se enviará al único método que maneja "application/vnd.COMPANY.systeminfo + json".

ESE método luego toma la información de control de versiones "fuera de banda" para manejar los detalles en el procesamiento (como seleccionar la clase adecuada para cargar a través de OSGi).

A continuación, cree un Proveedor con un MessageBodyWriter apropiado. El proveedor será seleccionado por JAX-RS para la aplicación/vnd.COMPANY.systeminfo + json tipo de medio. Depende de su MBW averiguar el tipo de medio real (basado de nuevo en esa información de versión) y crear el formato de salida correcto (de nuevo, tal vez enviando a la clase correcta cargada OSGi).

No sé si un MBW puede sobreescribir el encabezado Content-Type o no. De lo contrario, puede delegar el filtro anterior para reescribir esa parte en el camino de salida.

Es un poco intrincado, pero si desea aprovechar el despacho de JAX-RS y no crear métodos para cada versión de su tipo de medio, entonces esta es una ruta posible para hacerlo.

Editar en respuesta al comentario:

Sí, en esencia, que desea JAX-RS para despachar a la clase apropiada basándose tanto en Path y aceptar tipo. Es poco probable que JAX-RS lo haga de la caja, ya que es un caso marginal. No he analizado ninguna de las implementaciones de JAX-RS, pero es posible que pueda hacer lo que quiera modificando uno de los niveles de infraestructura.

Posiblemente otra opción menos invasiva es utilizar un viejo truco del mundo de Apache, y simplemente crear un filtro que reescribe su ruta basada en el encabezado Aceptar.

Por lo tanto, cuando el sistema obtiene:

GET /resource 
Accept: application/vnd.COMPANY.systeminfo-v1+json 

reescribes a:

GET /resource-v1 
Accept: application/vnd.COMPANY.systeminfo-v1+json 

A continuación, en la clase de JAX-RS:

@Path("resource-v1") 
@Produces("application/vnd.COMPANY.systeminfo-v1+json") 
public class ResourceV1 { 
    ... 
} 

lo tanto, sus clientes obtener la vista correcta, pero JAX-RS envía sus clases correctamente. El único otro problema es que sus clases, si miran, verán la ruta modificada, no la ruta original (pero su filtro puede incluir eso en la solicitud como referencia si lo desea).

No es ideal, pero es (la mayoría) gratis.

This es un filtro existente que podría hacer lo que quiera hacer, si no puede servir de inspiración para que usted mismo lo haga.

Answer 2

Una posible solución es utilizar uno @Path con

Content-Type: application/vnd.COMPANY.systeminfo- {version} + JSON

Entonces, dentro del método de la @Path dada, puede llamar a la versión de WebService

Answer 3

Si está utilizando CXF, podría use the technique specified here crear un nuevo proveedor de serialización (construyendo desde la infraestructura existente) que produce los datos en el formato específico deseado. Declare un par de ellos, uno para cada formato específico que desee, y use la anotación @Produces para que la maquinaria maneje el resto de la negociación por usted, aunque también podría ser una idea admitir el tipo de contenido JSON estándar también para que los clientes normales pueden manejarlo sin necesidad de asimilar su especialidad.La única pregunta real entonces se convierte en cuál es la mejor manera de hacer la serialización; Supongo que usted puede darse cuenta de eso por sí mismo ...

---

[EDIT]: Además de excavación en el CXF documentation conduce a la revelación de que tanto los @Consumes y @Produces anotaciones son considerados como ejes para hacer la selección. Si desea tener dos métodos que manejen la producción de la respuesta para diferentes tipos de medios, sin duda puede. (Deberá agregar los proveedores de serialización y/o deserialización si usa tipos personalizados, pero puede hacer la delegación de la mayoría del trabajo a los proveedores estándar). Me gustaría advertirle que debe hacerlo. aún así garantizar que el recurso indicado por la ruta sea el mismo en ambos casos; hacer lo contrario no es RESTful.