50 votos

DESCANSAR versionado api (solamente versión de la representación, no el recurso propio)

Eché un vistazo a las Mejores prácticas para la API de control de versiones?, pero no estoy muy convencido de la respuesta, entonces me pregunta el control de versiones que parte de nuevo con más específica ejemplo. Tengo dos URIs (uno con control de versiones como parte de la URI y el otro sin él):

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

Tengo mis dudas de si el primer enlace que expresa la idea del RESTO. Me parece http://xxxx/v1/user/123 confuso, ya que sugiere que habrá un mayor api-version algún día como http://xxxx/v2/user/123. Pero esto no tiene sentido en el RESTO de los términos, la versión de la api en sí es HTTP 1.0 o 1.1, que ya se ha enviado en el interior de la petición HTTP. Este RESTO de recursos centrada en vista difiere de otras api-interfaces como el JABÓN o Java interfaces (donde es común tener api-versiones en nombres completos).

En el RESTO, la única cosa en la cual el control de versiones que tiene sentido es la representación de ese recurso (por ejemplo, los nuevos campos se agregan o eliminan). Este control de versiones pertenece a la parte de contenido de la negociación 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 tal el contenido de la versión de negociación podría ser parte de la URI dentro de la ruta, pero me parece contra-intuitivo, ya que podría terminar con los diferentes URIs para el mismo recurso y mantener las redirecciones en algún momento.

En resumen: En el RESTO de las Uri no es api-control de versiones, sólo las versiones de los recursos de la representación. La representación de la versión info pertenece al contenido de la negociación (como queryParam o HTTP "Aceptar").

¿Qué te parece? En el que las cosas no está de acuerdo/de acuerdo?

36voto

Stefan Tilkov Puntos 1253

Estoy completamente de acuerdo; un URI expresa identidad, identidad no cambia cuando se introduce una nueva versión. Podría haber nuevos URIs para conceptos adicionales, por supuesto y Uri existente pueden redireccionar... pero incluyendo un "v2" en el URI huele RPCish a mí.

Tenga en cuenta que esto no tiene nada que ver con el resto, realmente, a partir de una perspectiva de resto es solo todos los caracteres.

10voto

yfeldblum Puntos 42613

Usted podría escuchar un X-API-Version encabezado de solicitud HTTP. Si existe el encabezado, el servidor debe usar esa versión de la API. Si el encabezado no existe, el servidor puede utilizar 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" } }
<

9voto

Darrel Miller Puntos 56797

Por lo que vale, estoy de acuerdo contigo, Manuel. Puedes ver mi razonamiento en esta pregunta http://stackoverflow.com/questions/972226/how-to-version-rest-uris

Hay un montón de personas que parecen estar en desacuerdo, pero yo no me preocuparía. Luce tu url realmente no tiene un gran impacto en su cliente mientras respeta la restricción de hipertexto.

2voto

cdent Puntos 51

Estoy de acuerdo en que usted no desea ver las versiones en las URIs de los recursos presentados en su API. Que hace no es "cool". También de acuerdo en que el que las representaciones que tienen más probabilidades de cambio.

Sin embargo, a continuación, plantear la cuestión de qué ocurre cuando se cambia el contenido de una representación particular. Por ejemplo, si el original de JSON representación de un frobnitz es

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

y desea agregar una "z" campo usted puede sentir que el cliente debe de tener un poco de conciencia de que ahora estamos en la versión 2 de algún tipo de sistema de datos.

No estoy seguro acerca de eso. Creo que tienes un par de opciones:

  • Hacer que sus clientes se flexible en la cara una suavidad en el cambio de las representaciones. En el ejemplo de arriba todavía estamos generando un JSON diccionario.
  • Si usted debe, poner una versión en la representación de sí mismo (una versión de campo en este ejemplo). Por hacer por lo que efectivamente está declarando una sub-representación en el JSON tipo de contenido. Creo que es bastante limitante, aunque.
  • Utilice sus propios tipos MIME y la versión de ellos: application/x-mi-especial-json1.0, application/x-mi-especial-json1.1. Esto le permite a la versión de su representación de forma independiente el uno del otro. De nuevo, con esto usted está haciendo una importante demanda de sus clientes para saber lo que está pasando.

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

1voto

MPV Puntos 698

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

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

Y si lo deseas, podrías volver la representación usando la API de última cuando soliciten así:

http://xxx/user/123.json

Personalmente prefiero otras soluciones pero esto es otro enfoque que no he visto se ha sugerido aquí todavía.

Iteramos.com

Iteramos es una comunidad de desarrolladores que busca expandir el conocimiento de la programación mas allá del inglés.
Tenemos una gran cantidad de contenido, y también puedes hacer tus propias preguntas o resolver las de los demás.

Powered by:

X