API REST de versiones. Cada API tiene su propia versión.

Lo que usted llama único API REST puede denominarse conjunto particular de recursos o recursos de la API REST. También puede considerarlo como la funcionalidad de una API REST. 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.

Luego, por lo que veo, las principales desventajas de su convención de nomenclatura del localizador de recursos propuesta:

• Para el usuario de la API , resultaría en localizadores de recursos mucho más complejos, menos predecibles, menos memorables y menos estables. Es más difícil recordar qué versión en particular se encuentra en cada recurso y conjunto de recursos ...
• Para el desarrollador (es) 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, a medida que se actualizan varios módulos ... A largo plazo, los inconvenientes anteriores pueden ser lo suficientemente desagradables ...

Al crear una API, uno de sus principales objetivos es hacer que sea fácil de usar ...

¿Podría encontrar una mejor manera de introducir un cambio importante o incluso la versión de la API REST con un encabezado HTTP?
Para conocer un poco más sobre el enfoque de los encabezados HTTP, vea otras respuestas a continuación y: enlace

Este es un enfoque aún mejor: use negociación de contenido para versionar su API con los encabezados Content-Type y 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ítelo con un tipo de contenido diferente en 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 varias versiones simplemente seleccionando con qué responder en función del encabezado Accept . Alternativamente, si desea mantener diferentes implementaciones para diferentes versiones, puede poner un proxy frente a diferentes versiones de su servicio que eligió a cuál enviar las solicitudes según el encabezado Accept .

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

La clave es que si la versión de cada punto final se realiza por separado, debe ser capaz de implementar cada punto final por separado.

Las API normalmente 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 juntas.

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

Además, deseará tener implementados al mismo tiempo v1 y v2 de su API. Normalmente, esto se hace 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.