restful example entre ejemplo diseño diferencia arquitectura rest versioning clean-urls

entre - rest api example



Cómo versionar URI REST (10)

Ah, me estoy poniendo mi viejo sombrero gruñón de nuevo.

Desde una perspectiva ReST, no importa en absoluto. No es una salchicha

El cliente recibe un URI que quiere seguir y lo trata como una cadena opaca. Pon lo que quieras en él, el cliente no tiene conocimiento de tal cosa como un identificador de versión.

Lo que el cliente sabe es que puede procesar el tipo de medio y le aconsejo que siga el consejo de Darrel. También, personalmente, creo que la necesidad de cambiar el formato 4 veces en una arquitectura tranquila debería generar enormes señales de advertencia de que estás haciendo algo realmente incorrecto, y pasar por alto completamente la necesidad de diseñar tu tipo de medio para la resiliencia del cambio.

Pero de cualquier manera, el cliente solo puede procesar un documento con un formato que pueda entender y seguir los enlaces que contiene. Debe saber sobre las relaciones de enlace (las transiciones). Entonces, lo que está en el URI es completamente irrelevante.

Yo personalmente votaría por http://localhost/3f3405d5-5984-4683-bf26-aca186d21c04

Un identificador perfectamente válido que evitará que cualquier otro desarrollador o persona que toque el sistema cuestione si se debe poner v4 al principio o al final de un URI (y sugiero que, desde la perspectiva del servidor, no debería tener 4 versiones, pero 4 tipos de medios).

¿Cuál es la mejor manera de versionar URI REST? Actualmente tenemos una versión # en el URI en sí, es decir.

http://example.com/users/v4/1234/

para la versión 4 de esta representación.

¿La versión pertenece a la queryString? es decir.

http://example.com/users/1234?version=4

¿O es mejor realizar versiones de otra manera?

Incluiría la versión como un valor opcional al final del URI. Esto podría ser un sufijo como / V4 o un parámetro de consulta como el que describió. Incluso puede redirigir el / V4 al parámetro de consulta para que admita ambas variaciones.

No haga una versión de las URL porque ...

  • rompes permalinks
  • Los cambios en la URL se propagarán como una enfermedad a través de su interfaz. ¿Qué haces con las representaciones que no han cambiado pero apuntan a la representación que tiene? Si cambias la URL, rompes clientes antiguos. Si abandona la url, es posible que sus nuevos clientes no funcionen.
  • Los tipos de medios de versionado son una solución mucho más flexible.

Suponiendo que su recurso está devolviendo alguna variante de la aplicación / vnd.yourcompany.user + xml, todo lo que necesita hacer es crear soporte para una nueva aplicación / vnd.yourcompany.userV2 + xml tipo de medio y mediante la magia de la negociación de contenido su v1 y Los clientes v2 pueden coexistir pacíficamente.

En una interfaz REST, lo más parecido a un contrato es la definición de los tipos de medios que se intercambian entre el cliente y el servidor.

Las URL que usa el cliente para interactuar con el servidor deben ser proporcionadas por el servidor integrado en las representaciones recuperadas anteriormente. La única URL que debe conocer el cliente es la URL raíz de la interfaz. Agregar números de versión a las URL solo tiene valor si construye urls en el cliente, lo cual no se supone que haga con una interfaz RESTful.

¡Si necesita hacer un cambio en sus tipos de medios que romperán sus clientes existentes, cree uno nuevo y deje en paz sus URLs!

Y para aquellos lectores que actualmente dicen que esto no tiene sentido si estoy usando application / xml y application / json como tipos de medios. ¿Cómo se supone que debemos versionar esos? Tu no eres. Esos tipos de medios son bastante inútiles para una interfaz REST a menos que los analice mediante la descarga de código, momento en el cual el control de versiones es un punto discutible.

Si los servicios REST requieren autenticación antes de su uso, puede asociar fácilmente la clave API / token con una versión API y hacer el enrutamiento internamente. Para usar una nueva versión de la API, se podría necesitar una nueva clave de API, vinculada a esa versión.

Lamentablemente, esta solución solo funciona para API basadas en autenticación. Sin embargo, mantiene las versiones fuera de los URI.

Si utiliza URI para el control de versiones, entonces el número de versión debe estar en el URI de la raíz de la API, para que cada identificador de recursos pueda incluirlo.

Técnicamente, una API REST no se rompe por cambios de URL (el resultado de la restricción de interfaz uniforme). Solo se rompe cuando la semántica relacionada (por ejemplo, un vocabulario RDF específico de API) cambia de una manera no retrocompatible (rara). Actualmente, muchas personas no usan enlaces de navegación (restricción HATEOAS) y vocabs para anotar sus respuestas REST (restricción de mensaje autodescriptivo) y por eso sus clientes se rompen.

Los tipos MIME personalizados y el control de versiones de tipo MIME no ayudan, porque no funciona el poner los metadatos relacionados y la estructura de la representación en una cadena corta. De c. los metadatos y la estructura cambiarán con frecuencia, y también el número de versión ...

Entonces, para responder a su pregunta, la mejor manera de anotar sus solicitudes y respuestas con vocabs ( Hydra , datos vinculados ) y olvidarse de las versiones o usarlo solo mediante cambios de vocabulario compatibles con versiones anteriores (por ejemplo, si desea reemplazar un vocabulario por otro).

Voto por hacer esto en mimo pero no en URL. Pero la razón no es la misma que otros tipos.

Creo que la URL debe ser única (excepto esos redireccionamientos) para ubicar el recurso único. Entonces, si acepta /v2.0 en las URL, ¿por qué no es /ver2.0 o /v2/ o /v2.0.0 ? O incluso -alpha y -beta ? (entonces se convierte totalmente en el concepto de semver )

Entonces, la versión en tipo mime es más aceptable que la URL.

Yo diría que hacerlo parte del URI en sí (opción 1) es mejor porque v4 identifica un recurso diferente de v3. Los parámetros de consulta como en su segunda opción se pueden usar mejor para transferir información adicional (consulta) relacionada con la solicitud , en lugar del recurso .