Versiones API REST. Cada API tiene su propia versión

Es muy común especificar la versión de las API REST en la URL, específicamente al comienzo de la ruta, es decir, algo como:

POST /api/v1/accounts
GET /api/v1/accounts/details

Sin embargo, no he visto ningún diseño en el que la versión esté asociada con cada API. En otras palabras, mantenemos la versión de cada API por separado. es decir:

POST /api/accounts/v2
GET /api/accounts/details/v3

Usando este enfoque, incrementamos la versión API de la API específica cuando se necesita un cambio de ruptura, no es necesario incrementar la versión de las API completas.

¿Cuáles son los inconvenientes de usar este estilo en lugar del estilo común?

— Eng.Fouad
fuente

Respuestas:

Lo que llama API REST individuales podría llamarse el conjunto particular de recursos o recursos de la API REST . También podría verlo como las funcionalidades de REST API . Como cualquier tipo de software, todo el paquete está versionado / actualizado, no funcionalidades o recursos únicos.

Su pregunta tendría sentido en el contexto donde los recursos del paquete REST API son modulares y, por lo tanto, potencialmente desarrollados y versionados por separado.

Entonces, por lo que veo, los principales inconvenientes de su convención de nomenclatura de localizador de recursos propuesta son:

Para el usuario API , resultaría en localizadores de recursos mucho más complejos, menos predecibles, menos memorables y menos estables.
Para los desarrolladores de módulos , ahora es más trabajo tener que lidiar con esta versión en su propio localizador de recursos.
Los cambios en los localizadores de recursos se vuelven mucho más frecuentes, ya que hay múltiples módulos que se actualizan, por lo que los inconvenientes anteriores son exponenciales ...

Al crear una API, uno de sus objetivos principales es facilitar su uso ...

¿Podría encontrar una mejor manera de introducir un cambio importante o incluso versionar la API REST con quizás un encabezado HTTP?

Para saber un poco más sobre el enfoque de encabezados HTTP, vea otras respuestas a continuación y: https://www.troyhunt.com/your-api-versioning-is-wrong-which-is/

— ClemC
fuente

Aquí hay un enfoque aún mejor: use la negociación de contenido para versionar su API con los encabezados Content-Typey Accept:

POST /api/accounts
Accept: application/vnd.my-api.account.v1+json

201 Created
Location: /api/accounts/285728
Content-Type: application/vnd.my-api.account.v1+json
{ ... account data here ... }

Para obtener una versión diferente, simplemente solicítela con un tipo de contenido diferente Accept. De esta manera, las versiones particulares que admite su servidor son completamente independientes de su estructura de URL. El mismo servidor podría admitir múltiples versiones simplemente eligiendo con qué responder según el Acceptencabezado. Alternativamente, si desea seguir con diferentes implementaciones para diferentes versiones, puede colocar un proxy frente a diferentes versiones de su servicio que seleccionó a cuál reenviar las solicitudes en función del Acceptencabezado.

Esto también le permite admitir nuevos formatos con diferentes semánticas (no solo versiones diferentes) en los mismos puntos finales. Por ejemplo, PUBLICAR una lista de cuentas /api/accountspodría significar la creación de lotes, y no necesitaría crear un punto final de API separado para ello.

— Jack
fuente

omg, el encabezado de aceptación debe ser la peor opción de señalización de versión. use un encabezado de versión si puede, ruta de URL si debe (es decir, enrutamiento de AWS)

— Ewan

@Ewan ¿Por qué? Un encabezado de versión personalizado implica que diferentes versiones son el mismo recurso sin informar a los intermediarios que el contenido podría ser diferente. Un proxy de almacenamiento en caché no sabría usar su encabezado para no servir respuestas en caché v1 a solicitudes v2.

— Jack

use el encabezado de respuesta variable, si aún no está usando no-cache para las solicitudes de API. el tipo de contenido ya tiene un significado, subdividirlo para su uso privado solo dificulta la vida de los consumidores

— Ewan

@Ewan Para eso están la vndparte y la +sintaxis del tipo: para indicar que este es un subtipo de application/jsontipo específico del proveedor . Esto es exactamente para lo que están diseñados los tipos de contenido. Su recurso está disponible en múltiples formatos. Le está pidiendo al cliente que elija qué formato quiere. Además, no hay ninguna razón por la cual las solicitudes de API no puedan usar la semántica de almacenamiento en caché HTTP estándar.

— Jack

si corrige un error en myapi v2, no devolverá un nuevo tipo mime.

— Ewan

La clave es que si versiona cada punto final por separado, debe poder implementar cada punto final por separado.

Las API generalmente tienen una versión porque todos los puntos finales están en la misma base de código y, por lo tanto, tienen dependencias compartidas y se implementan juntos.

Si no está actualizando la versión cuando realiza un cambio porque "Oh, estoy bastante seguro de que mi cambio no afecta eso", entonces se meterá en problemas cuando cometa un error.

Además, querrás tener v1 y v2 de tu API implementadas al mismo tiempo. Esto normalmente se realiza implementando cada versión en un servidor separado y enrutando el tráfico en consecuencia.

Si no tiene una única versión de API, esto se vuelve mucho más complejo.

— Ewan
fuente