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?

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/

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.

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.