rest api versions

REST api versioning(solo versión de la representación, no del recurso en sí)

Question

Eché un vistazo a las mejores prácticas para el control de versiones de API. , pero no estoy del todo convencido de la respuesta, entonces me cuestiono la versión de la versión de nuevo con un ejemplo más específico. Tengo dos URI (uno con control de versiones como parte del URI y otro sin):

http://xxxx/v1/user/123    -> favored solution in discussed thread
http://xxxx/user/123             

Tengo mis dudas sobre si el primer enlace expresa la idea de REST. Encuentro que http://xxxx/v1/user/123 confuso, ya que sugiere que algún día habrá una versión api más alta, como http://xxxx/v2/user/123 . Pero esto no tiene sentido en términos REST, la versión api en sí es HTTP 1.0 o 1.1, que ya se envía dentro de la solicitud HTTP. Esta vista centrada en recursos REST difiere mucho de otras interfaces api como SOAP o interfaces Java (donde es común tener api-versiones en nombres calificados).

En REST, lo único que tiene sentido es la representación de ese recurso (por ejemplo, se agregan o eliminan nuevos campos). Este control de versiones pertenece a la parte de negociación de contenido como:

http://xxx/user/123 + HTTP ''Accept'' Header -> Content negotation through header
http://xxx/user/123?v=1                    -> for perma-links/hyperlinks

También se podría argumentar que dicha negociación de contenido de versión podría ser parte del URI dentro de la ruta, pero me resulta contraintuitivo, ya que podría terminar con diferentes URI para el mismo recurso y mantener las redirecciones en algún momento.

Para resumir: en los URI de REST no hay api-versiones, solo versiones de la representación del recurso. Representación version-info pertenece a content-negotiation (como queryParam o HTTP ''Accept'').

¿Qué piensas? ¿En qué cosas estarías en desacuerdo / estoy de acuerdo?

Answer 1

Encuentro que http://xxxx/v1/user/123 confuso, ya que sugiere que algún día habrá una versión api más alta, como http://xxxx/v2/user/123

No sugiere eso, como sea que tengas esa habilidad en el futuro.

Pero esto no tiene sentido en términos REST, la versión api en sí es HTTP 1.0 o 1.1, que ya se envía dentro de la solicitud HTTP.

La versión de YOUR API y la versión de HTTP que está utilizando para realizar solicitudes no tienen que ser iguales.

También se podría argumentar que dicha negociación de contenido de versión podría ser parte del URI dentro de la ruta, pero me resulta contraintuitivo, ya que podría terminar con diferentes URI para el mismo recurso y mantener las redirecciones en algún momento.

Está bien tener la versión como un parámetro URI como lo demostró.

http://xxx/user/123?v=1 -> para enlaces permanentes / hipervínculos

Answer 2

Acepto que no desea ver versiones en los URI de los recursos presentados en su API. Eso los hace no "cool". También acepta que son las representaciones las que tienen más probabilidades de cambiar.

Sin embargo, plantea la pregunta de qué sucede cuando cambias el contenido de una representación particular. Por ejemplo, si su representación original de JSON de un frobnitz es

{"x": "bam", "y": "hello"}

y si desea agregar un campo "z", puede sentir que el cliente debería tener conocimiento de que ahora estamos en la versión 2 de algún tipo de esquema de datos.

No estoy seguro de eso. Creo que tienes algunas opciones:

• Haga que sus clientes sean flexibles ante las representaciones que cambian suavemente. En el ejemplo anterior, aún estamos generando un diccionario JSON.
• Si debe, ponga una versión en la representación en sí (un campo de versión en este ejemplo). Al hacerlo, declaras efectivamente una sub-representación dentro del tipo de contenido JSON. Aunque creo que eso es bastante limitante.
• Use sus propios tipos MIME y vuélvalos a versionar: application / x-my-special-json1.0, application / x-my-special-json1.1. Esto le permite versionar sus representaciones independientemente una de la otra. Nuevamente, con este usted está haciendo una gran demanda a sus clientes para saber qué está pasando.

En general, creo que quiere optimizar su API y sus representaciones para clientes que usted no ha inventado usted mismo; unos que otras personas crearán al descubrir sus recursos. Creo que esto es útil incluso en el caso en que se está haciendo algo que es privado porque se basa en una restricción de diseño útil que ayudará a que su sistema sea más robusto.

Answer 3

Estoy completamente de acuerdo; un URI expresa identidad, la identidad no cambia cuando se presenta una nueva versión. Puede haber nuevos URI para conceptos adicionales, por supuesto, y los URI existentes pueden redireccionar ... pero incluir un "v2" en el URI me huele a RPCish.

Tenga en cuenta que esto no tiene nada que ver con REST, en realidad, desde una perspectiva de REST todo son solo caracteres.

Answer 4

Otro enfoque podría ser decir que "una representación tiene múltiples API":

http://xxx/user/123/api/1.json

Y si lo desea, puede devolver la representación utilizando la última API cuando solicite de esta manera:

http://xxx/user/123.json

Personalmente, me gustan otras soluciones mejor, pero este es otro enfoque que aún no he visto aquí.

Answer 5

Para REST, lo que la mayoría de las respuestas olvida es el elemento de datos. Supongo que las API de múltiples versiones aún comparten esa misma capa de datos. Esto significa que la capa de datos te obliga a pensar de una manera compatible hacia atrás. Los grandes cambios que deben hacerse solo son posibles si su API cambia de una manera compatible con versiones anteriores. En la práctica, esto significa que las propiedades adicionales se agregan de forma silenciosa a sus entidades al tiempo que usan la depreciación por fecha en su documento API para indicar cuándo se eliminará algo. Lo ideal sería utilizar un esquema de registro con la dirección de correo electrónico de los usuarios de la clave API, para que pueda notificarles sobre la desaprobación dentro de un cierto alcance (a la Facebook). Por lo tanto, no creo que deba especificar una versión en ningún lugar.

Answer 6

Por lo que vale, estoy de acuerdo contigo, Manuel. Puedes ver mi razonamiento en esta pregunta Cómo versionar URI de REST

Hay muchas personas que parecen estar en desacuerdo pero no me preocuparía. El aspecto de su URL realmente no tiene un gran impacto en su cliente siempre que respete la restricción de hipertexto.

Answer 7

Puede escuchar un encabezado de solicitud HTTP de X-API-Version . Si el encabezado existe, entonces el servidor debe usar esa versión de la API. Si el encabezado no existe, el servidor puede usar la última versión de la API.

> GET /user/123 HTTP/1.1
> Host: xxx
> X-API-Version: >=1.5.1, <2.0.0
> Accept: application/json
>

< HTTP/1.1 200 OK
< X-API-Version: 1.6.12
<
< { "user": { "id": 123, "name": "Bob Smith" } }
<